Understanding API Invocations

API developers who provide or consume APIs will benefit a great deal from being able to understand the anatomy of an API implementation.

The API provider implements the API and publish the API for consumers. The API will reside on a server waiting for requests to come in.

API invocation when consuming an API is always initiated by the client side. That involves constructing a request message and sending that over a network to the server. Sometimes, the consumer is termed the front end.

Upon receiving the request message, the server processes the request at the backend. Before dispatching the request to the resource, the message validation and operation identification would be done by the middleware stack, or the application framework, being used to implement the API.

Then, the API will be presented with the request message. The server will process the request and carry out the operations invoked and prepare the response message. The response message from the API with the intended representation will be handed over to the network layer to be delivered to the API consumer.

When the client application, in other words, the API consumer, receives the response message, it can validate the message format and had it over to the client application logic to be processed.

As you can notice so far, API invocation involves a request response pair. Here is the sequence of activities involved in the invocation.

  1. API consumer client application creates the request message
  2. Request message is sent to the API server over the network
  3. API provider receives the request message
  4. API request is handed over to the API for processing and carry out the intended operations
  5. API creates the response message based on operation execution
  6. Response message is sent to the consumer client application over the network
  7. API consumer receives the response message
  8. API consumer process the API response and acts accordingly

This sequence of execution needs to be well understood by API developers to be able to understand the execution flow and be able to debug the applications and APIs.

API request and response sequences along with the invocation semantics such as HTTP methods are documented in the API documentation. APIs are documented using a markup language like Swagger.

The documentation provides details on

  • What operations the API supports?
  • What are request and response message formats?
  • Does your API need some authorization?

When you relate the API invocation sequence of activities and relate the same to the documentation in terms of request and response message formats, it becomes much simple for API developers to test, debug and verify the API usage.

There are tools to help capture messages while in transit to help look at the request message body and HTTP headers. If you want to make sure that the API responds properly from the API server, you can use a tool such as Postman API client to send requests to API to inspect and verify responses.

For debugging on the server side to see if you received the correct request form the API client, you can use logging and tracing capabilities of your API platform to help debug the requests.