5.2 REST APIs in Practice

If a client-side developer wishes to interact with an API, the developer need to place a request that contains a certain amount of information:

  • The Endpoint: The endpoint is the URL at which the developer is making a request, and will define the kinds of information that the develop can receive. The structure of an endpoint is as follows:

    • An endpoint always begins with a root, which typically represents the high-level URL that the developer is interacting with. For example, if a developer is interacting with Facebook’s API (Facebook.com, not Facebook’s subsidiary companies’ APIs), the request will always start with https://graph.facebook.com.

    • From there, the client-side developer must specify the path by which to retrieve the desired information. As a metaphor, one can think of this sub-section of the endpoint as an automated answer machine, where the developer presses numbers to navigate through a menu to the intended destination. As an example, if a developer wanted to see who all of someone’s Facebook friends, that path would be /user-id/friends. It’s important to note that this looks exactly the same if the developer were utilizing Spotify’s API to obtain the same information, going through links instead. To see who a user’s friends are on Facebook via Spotify, the developer would still need to click to the user’s profile (user-id), and then click again to see the user’s friends.

  • The Method: The method defines the type of request that the client-side developer sends to the server, which are usually one of five types, and allow for all the basic CRUD (create, remove, update, delete) operations:

    • GET: The developer gets the resource from the server, i.e. get a user's Facebook friends.

    • POST: The developer creates a new resource on the server, i.e. share a photo to a user’s Facebook profile.

    • PUT: The developer overwrites a resource on the server, i.e. adding changing a user’s profile picture on Facebook.

    • PATCH: The developer updates parts of an existing resource in the server, i.e. changing just a user’s description in the user’s profile page. PUT and PATCH are fairly similar and choosing which one to use is case specific and a frequent topic of debate [33].

    • DELETE: The developer removes a resource from the server, i.e. removing a Facebook post.

  • The Headers: Headers provide information to the client-side party about how information can be handled by the client-side application, namely the kinds of access an individual is allowed. For example, updating a user’s Facebook profile through Facebook’s API is allowed only by that user him or herself, thus rendering that the user of the client-side application must proves an access-token that proves the server has given them permission to make changes to that user’s profile; that access-token would be included as a header, such that the client-side application can provide the desired actions to their end-user. An example list of headers can be found here [34].

  • The Data (or Body): The Data (or Body) provides information that the client wishes to revert to the server and is only used to perform a create, update, or delete action. For example, if a user wants to change his or her Facebook profile picture on a client-application that utilizes Facebook’s API, the message reverted to the Facebook server must include the image that needs to be uploaded as the replacement.

To put this all together, we construct an example query and response, shown below, illustrating a simple yet precise interaction with a REST API:

  • Request: api.example.com/GET/users/10

  • Response:

 “user”: {
                   “id” : 10,
                   “name” : “Satoshi Nakamoto”,
                   “nickname” : “Seb”,
                   “height” : 180,
                   “Image_url” : “/images/10.jpg”

Figure 5.2.1: REST API Response.

Last updated