API — definition and examples

Many softwares and devices around us use API to perform their functions. Yet, I didn’t really appreciate how they work.

So here are the basics.

API definition

API is a mechanism that allows 2 software components to talk to each other using a defined set of protocols. One party requests for information, the other party responds. This allows information or resources to be passed from one software to another.

If you have an app, you may want to build an API for it so that it can interact with other softwares.

The party that requests for information is called client. When our mobile app sends request to Google for information, our mobile app is the client.

The party that responds with information is called the server. Google responds with search information, Google is the server.

Types of REST APIs

REST stands for Representational State Transfer. There are many ways 2 software components can use REST APIs to ‘communicate’:

POST — to create new resources on the server. Example: You can send a POST API with user account information to an app to create an account in the app.

PUT — to update resources on the server. Example: an authorised third party app sends a PUT API with your updated home address to update the database of your Uber account.

GET — to display/read resources from the server. No request body needed. Examples: Travel apps send GET API to airlines database to display list of flight prices and seats on their app. ActiveSG sends a GET API to Google Fit to display my step counts logged in Google Fit on their app.

DELETE — to delete resources on the server. No request body needed. Example: At your direction, gmail sends a DELETE API to Shopee’s API to delete your email account from Shopee’s ad mailing list.

EXAMPLE OF POST API: To create new resources on the server

All sessions start with a POST API to sign in. You send a POST request with user credentials in the body. If valid, the server responds back with an AccessToken for you to use in subsequent calls.

REST APIs are implemented over HTTP protocol, and data is usually transferred in JSON format (key-value pairs).

POST Request:

• URI — the API endpoint that points to a resource. For POST API, it contains Path Parameter only.
• HTTP Headers — set of attributes that tell us something about the metadata of the API request. Nothing to do with the actual data. ie. Language = EN means that the language for this API exchange is English.
• Request payload — actual data such as your username and password, to create an account.

POST Response:

• Response body — your account ID.

Example of sending POST API to create a playlist on Youtube:

POST URI:

POST {base_URL}/playlists?part=snippet

POST Request body:

 Request body:
  {
    'snippet': {
      'title': 'New playlist', 
      'description': 'Sample playlist for Data API',
     }
  }

POST API is not idempotent. Every time you send a POST API, the state of the server changes. You create more data or resources within the server.

EXAMPLE OF GET API: To get/read data from server

GET Request:

• URI (need a path parameter, mention the resource id that you want to fetch. For GET, you may need a Query Parameter)
• No need for request body

GET Response:

• Response body — what you requested for: the seats, price, step counts.

Example of using GET API to see channel information from Youtube:
GET Request:

GET {base_URL}/channels?part=contentDetails&mine=true

No request body.

GET response:

{
  "id": {CHANNEL_ID},
  "kind": "youtube#channel",
  "etag": etag,
  "contentDetails": {
    "relatedPlaylists": {
      "likes": {LIKES_PLAYLIST_ID},
      "favorites": {FAVORITES_PLAYLIST_ID},
      "uploads": {UPLOADS_PLAYLIST_ID},
      "watchHistory": {WATCHHISTORY_PLAYLIST_ID},
      "watchLater": {WATCHLATER_PLAYLIST_ID}
    },
    "googlePlusUserId": string
  },
}

GET APIs are idempotent. This means that you can get same response multiple times if you send the request multiple times. No matter how many times you send a GET API, the state of server remains the same.

HTTP Status code

After the client sends out the request, the client should receive a HTTP status code regarding the request.

HTTP status codes can be grouped into these broad categories:

• 2XX — Success! Client’s request was accepted.
• 3XX — Redirection. Client must take some additional action to complete the request.
• 4XX — Bad request from client. Example: expected data not sent in correct format.
• 5XX — Bad request from server.

In each category of status code, there are more specific codes that allows the client and server to understand what happened.

Implement access security to your API

If a server provides an open source API, bots and malicious actors can jam up the servers with huge volume of API calls. There are 2 measures servers can (need to) adopt to prevent that from happening.

Create a unique API key for each authorised entity to access your API. These API keys are unique to the entity of the client — given only to those who have been granted access to the application. When clients sends a request with this API key, server looks up the API key in the database, identifies the user, and processes the request.

Require clients to login and respond with an AccessToken. Client sends a POST request to a login endpoint and pass login credentials (ie. UserName and password). If these are valid, server responds with an AccessToken (an encoded string that contains client’s data). AccessToken contains client’s information, hence the server doesn’t need to check database.

This way, client can use the AccessToken string in the header along with their API requests to the server for all the calls within the session. API decodes the token, retrieves the client’s details. If it’s a valid token, API sends back successful response. Example of implementing authorisation: OAuth2.0.

These 2 measures allows servers to keep track of who had been sending API requests and make sure they are indeed authorised requests.

Additional notes

Path Parameter: specifies the location of a resource.

ie. www.domain.com/customer/John — We want to fetch all data for John.

ie. www.domain.com/customer/John/order — This gets all order data for John.

Query Parameter: fetch resources with a filter through the list. You can also use this to limit the body of response that we fetch from server.

ie. www.domain.com/customer?name=Amy. We want list of customers whose names contain Amy.