How do APIs work?

How do they work?

When you type in a webpage URL into your browser, it makes a call to that website server asking for some information in return, in this case the website is returned as a series of files and folders which your browser knows exactly how to display. APIs work similarly, an application is making a Request to an API through an endpoint (the URL) and is typically expecting a Response in return

Types of requests

An API request comes in the form of an HTTP call, which is broken down into methods

• a GET call is typically a simple request for information. Show me a webpage, give me the details of a user, or search for a list of users
• a PATCH call is usually a partial update to an existing record. Update a file name or change some metadata on an existing file
• a PUT call is typically used when sending data to a service, frequently a completely new record or replacing an existing record entirely
  • Sometimes a PUT call is used for very complex GET calls, such as Search
• a DELETE call is used to erase a record, such as deleting a user or deleting a piece of content
  • Depending on API, you might be disabling a record as opposed to deleting it complete. This is true for the Delete a user endpoint.

🚧

Some endpoints support multiple types of calls

GET file information/properties & PATCH Change file information/properties are calls to the same endpoint, but they behave differently based on the HTTP request type. Fortunately, these endpoints have different requirements in order to function, as the PATCH call asks for much more detail in a specific format so it will be difficult to accidentally update data when you are just looking for file proeprties

However, GET Retrieve a user by ID and DELETE a user by ID have identical input requirements, so it is perfectly possible to delete a user that you meant to search for if you are not careful

Types of responses

After sending a request to an API, the service will typically wait for a response from the API. They responses come in the form of an HTTP Status Code and may contain additional information. Below is a breakdown of common status codes and their typical definition

• 2xx: Request received, understood, and accepted
  • 200: "OK" with additional details
  • 201: "Created" with additional details
  • 204: "OK" without additional details
• 3xx: Additional information required
• 4xx: An error occurred while handling your request - Commonly an invalid parameter
• 5xx: An error occurred - Commonly a server error

📘

RESTful APIs

Our APIs are RESTful, which means that we have a specific system architecture which handles things like statelessness, caching, and the separation of client and server side code.
If you don't know what any of that means, don't stress.