CODEWITHSUNDEEP
restapidjango-rest-framework
blueFast
blueFast

Reputation: 44381

Return several resources in REST call

I am providing access to a REST endpoint where some aggregates are computed. Let's say the model is as follows:

Purchase:

Now I want to offer a timeline of purchases, aggregated on a weekly basis, and partitioned by group. This will produce the following data:

{
  "ELECTRONICS": [{"week": "2018WK1", "amount": 1000.0}, ...],
  "FOOD": [{"week": "2018WK1", "amount": 2000.0}, ...],
  "FURNITURE": [{"week": "2018WK1", "amount": 3000.0}, ...],
  ...
}

Some things to note:

The URL for the request would be something like: /api/weekly_purchases/2018

How can I offer these kind of resources in a REST API?

Upvotes: 0

Views: 65

Answers (2)

Roman Vottner
Roman Vottner

Reputation: 12839

As already mentioned in my initial comment or by VoiceOfUnreason the same techniques that apply to the browser-based Web apply to any interaction model used by applications that follow the REST architecture principles. As also mentioned by VoiceOfUnreason a client would initially request some state returned from the entry-point, i.e. https://api.acme.com that will return a collection of links a client can use to progress its task. In order for the client to determine which URL to invoke the response should give the URI a meaningful name (link-relation name). IANA maintains a list of already specified link-relation names you should use if possible or define your own one in further standards. According to Fielding the specification of media-types and link relations is one of the most important things to do if developing a RESTful architecture.

For simplicity I use a simplified HAL-JSON syntax throughout the example.

{
  ...
  "_links": {
    "self": {
      "href": "https://api.acme.com"
    },
    ...
    "archives": {
      "href": "https://api.acme.com/weekly_purchases"
    },
    ...
  }
}

According to the HTML 5 spec archives

indicates that the referenced document describes a collection of records, documents, or other materials of historical interest

The link relation name therefore describes the intent of the URI which client can use if interested in retrieve a collection of historical entries. The client does not really have to know the exact URI as he will learn it by simply following the link relation's target href element. This allows the server to change its internal URI structure anytime it has to without actually breaking clients.

On following the archives target URI a client will not really know yet how the actual data has to be retrieved as the URI and the link relation name are to generic. But the server will guide the client through its task. A response on the invocation of the abovementioned target URI might return the following content:

{
  "year": [
    "2018":  {
      "_links": {
        "chapter": {
          "href": "https://api.acme.com/weekly_purchases/2018"
        }
      }
    },
    "2017": {
      "_links": {
        "chapter": {
          "href": "https://api.acme.com/weekly_purchases/2017"
        }
      }
    },
    ...
    "2014": {
      "_links": {
        "chapter": {
          "href": "https://api.acme.com/weekly_purchases/2014"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://api.acme.com/weekly_purchases"
    },
    "first": {
      "href": "https://api.acme.com/weekly_purchases"
    },
    "next": {
      "href": "https://api.acme.com/weekly_purchases?p=1"
    },
    "last": {
      "href": "https://api.acme.com/weekly_purchases?p=3"
    },
    "current": {
      "href": "https://api.acme.com/weekly_purchases"
    }
  }
}

This response basically only teaches the client that there are multiple years available to choose from and the client has to decide which year s/he is interested in an invoke that URI to proceed its task. The next, last and first link relation indicate that there are multiple pages available as only the 5 years per page are returned. The current link relation name will always point to the most recent entry in the collection, which is the initial page (or first page) of the collection-resource. Note further how multiple different link-relation names may point to the same URI. Sometimes it isn't really clear which link relation names to use as their semantics partly overlap. This is just an example on what can be done with link relation names.

A client can now further drill down to the purchases done in 2018 by following the chapter link for 2018. A response on invoking that URI may now look like this:

{
  "purchase": [
    "W1": {
      "sum": 1263.59,
      "currency": "Euro",
      "_links": {
        "about": {
          "href": "https://api.acme.com/weekly_purchases/2018/1"
        }
      }
    },
    "W2": {
      "sum": 569.32,
      "currency": "Euro",
      "_links": {
        "about": {
          "href": "https://api.acme.com/weekly_purchases/2018/2"
        }
      }
    },
    ...
    "W48": {
      "sum": 72.98,
      "currency": "Euro",
      "_links": {
        "about": {
          "href": "https://api.acme.com/weekly_purchases/2018/48"
        }
      }
    },
    "current": {
      "sum": 72.98,
      "currency": "Euro",
      "_links": {
        "about": {
          "href": "https://api.acme.com/weekly_purchases/2018/48"
        }
      }
    }
  ],
  "_links": {
    "index": {
      "href": "https://api.acme.com/weekly_purchases"
    },
    "self": {
      "href": "https://api.acme.com/weekly_purchases/2018"
    },
    "current": {
      "href": "https://api.acme.com/weekly_purchases/2018"
    },
    "prev": {
      "href": "https://api.acme.com/weekly_purchases/2017"
    },
    "prev-archive": {
      "href": "https://api.acme.com/weekly_purchases/2017"
    },
    "first": {
      "href": "https://api.acme.com/weekly_purchases/2000"
    }
  }
}

You could either add content here to the weekly summary or hide it down the road by following the about link only if clients are really interested in such details.

Note further: As weekly_purchases is just a string without meaning to the client it does not really know what it means. You could therefore also rename it to purchase-archive or something like that and introduce a further choice to the client and let the client determine whether it wants a weekly, monthly or total summary of that year.

REST is about providing choices to a client and teach it what the actual choices are intended for. One of the aims the RESTful architecture tries to solve is the strict coupling between clients and servers which prevent the latter one from evolving freely and the former ones to break if the latter one changes unexpectedly. This decoupling only works if certain standards are used to increase the likelihood for interoperability. Usually out-of-band information (pre-existing knowledge about the API and how to interact with it) is leading to a coupling. Even Fielding stated that some prior knowledge is needed though but not encoded directly into the application but on reusing certain standards like well-defined and stable media-types and link-relation names.

Upvotes: 1

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57257

Return several resources in REST call

How would you do it as a web page?

Somewhere on your web site would be a link, with text "this week's summary" (or whatever the appropriate concept is in the language of your domain). If a user clicked that link, the browser would do a GET on one URL, which would go to the server, aggregate all of the data together, and return the result.

So do that?

REST doesn't care about the spelling of the URI (the browser doesn't try to interpret the URL, except in very shallow generic ways), so /api/weekly_purchases/2018 is fine.

The trick is recognizing that a report summarizing purchases in the current fiscal year, broken out by week, is a resource. It may have data in it that duplicates the information in other resources, even data in many other resources, but it is still a resource itself.

Upvotes: 2

Related Questions