What is an API and how does Outsourcify use them?

What is an API and how does Outsourcify use them?
Categories
Technologies
Author

Miro Lehtonen

Project Manager & Lead Developer
Date

The development of an API is one of the major parts of most of our web app projects. The API (Application Programming Interface) defines the technical details of how the user interface modules interact with the data interface modules, enabling a data flow between our web browser and the database. In this context, the development of the API covers more than just the interface as it also includes the server-side application running behind the API. One of the major benefits of this modular structure is that the same API can serve multiple clients, not only the browser UI but also mobile apps and IoT apps.

From the project manager’s perspective, the API module can be developed independently of the client apps, by developers whose expertise is in the backend technology, e.g. PHP engineers. The client app developers would also play a role by setting requirements for the API and eventually testing the API.

Separation of concerns

One of the most fundamental principles in software design is the separation of concerns which divides the application code into modules that don’t have overlapping responsibilities. For example, the API is responsible for finding data in the database, whereas the presentation modules are responsible for displaying the data to the user. This kind of separation makes a lot of sense when the same user and application data is shared among multiple clients, e.g. an Android app, an iPhone app, and a web app running in a browser. From a security perspective, the separation adds another layer of security to the system. When vulnerable client-side apps are not directly connecting to the database, they also don’t need to worry about keeping the database credentials secure.

The separation of responsibilities between the API and its client apps is not always clear-cut. For example, formatting a timestamp into a human-readable date expression is an operation that both the API server and the client browser could carry out. In these cases, the factors specific to the application will determine who takes the responsibility.

Sometimes the separation goes all the way, so that not only can the API and its clients be developed by different developers in the same department but they can be developed by separate organizations altogether. The website for Ecotrade is a recent example where Outsourcify was responsible for the web API while the mobile apps were developed in Europe. 

Technical point of view

From a technical point of view, a client application sees the API as a set of endpoints accepting HTTP requests and returning HTTP responses where an endpoint is defined by an HTTP method and the URL. For example, sending a request to “GET /blog/posts” endpoint would return blog posts as a response, whereas sending a request to “POST /blog/posts” endpoint would create a new resource on the server.

For each endpoint, the API defines what it requires of the requests and what the responses are. Typical requirements are about the structure of the data that is sent in the request body, e.g. a blog post must have a title. Equally important are the more technical requirements for the HTTP headers which can state that the content must be in a JSON format, the request must be authorized by the API, and that the origin of the request must be one that the API has whitelisted.

The clients of the API also need to know what the responses look like so that they can be adequately processed. This includes both the expected “operation successful” responses accompanied with data as well as the unexpected responses containing error messages.

What are external APIs?

External APIs are technically similar to the server-side API that provides application data for the user interface: they are accessible through a set of URLs that accept requests from client apps running on web servers, or web browsers. These APIs are managed and maintained by a third party that allows controlled access to their resources. For example, Google Maps data can be accessed through multiple different APIs such as Roads API, Directions API, Places API, etc. Access requires an access key provided by the resource owner and service provider, Google so that they can authenticate each request and monitor the usage by each client.

The access to an external API is not always free and rarely unlimited. The access key usually has a validity period which may be linked to a membership or a subscription with a billing plan. The service providers also have the right to discontinue their service for any reason and at any time without liability, as did Google recently with their PaLM API.

The service level agreements are therefore a good read when paying for access to an external API.

API errors & troubleshooting

Once in a while, our activities on a website are interrupted because something goes wrong with the API. We may see a never-ending loading icon animation if the API is not responding normally, or some data may be completely missing if the API fails to send it to the user interface. While a well-implemented client application can handle all the cases where the API malfunctions or is out of reach, it cannot recover missing data. For example, if the API cannot reach the database and authenticate the user, we will be stuck with the retry dialog of the UI.

The first step in handling the exceptions is to implement error handling for all possible API errors so that the client application stays responsive – and able to display retry dialogs. Second, we want to log all the exceptions on the server with enough information so that the developers will know how to prevent the errors from occurring in the future, not only by fixing bugs but also by implementing recovery mechanisms for cases where upstream servers, i.e. database servers, are experiencing errors or cannot be reached. Finally, we need to document the behavior of the API so that also the unrecoverable errors look like features and not bugs.

External APIs are often more robust and stable than our freshly developed web app backend API but the unexpected still happens. The possible reasons include changes in the external API, over-quota usage, and expiration of the access key. Most service providers let us access a developer console or dashboard where we can view the usage of the access key, including statistics about bad requests, failure responses, and activity and error logs. Troubleshooting is so much easier when the logged errors trigger notifications that are linked to appropriate documentation.

Technology

The technical implementation of an API for a web app client does not require a specific technology, framework, or programming language. The common choices at Outsourcify include some of the most popular backend technologies, e.g. a Symfony PHP application served by the Apache web server running in a Linux environment. A number of our projects rely on the API Platform which is a framework built on top of Symfony. By annotating our PHP code, we define API resources with a roundtrip from the database to the UI client and back. The data serialization and normalization steps that handle conversions between raw relational data and a hierarchical JSON format can be customized with little effort. In many cases, this reduces the need to write custom code to implement the basic CRUD operations for the common entities of the application, which speeds up project progress. The features included in the API Platform are highly configurable so that the details can be customized to fit various applications and environments.

Documentation

Developers use the API documentation (API doc) as a frequent point of contact with the API as it answers all the technical questions that client app developers may have about the API. When the client-side development is separate from the API development, it is especially important to have a clear and accurate API specification. Inaccurate or incomplete documentation leads to instability in client apps: we cannot decide who to trust, the API or the documentation, as one of them will likely be fixed in the future.

OpenAPI is a commonly used standard format for presenting the specifications of the API endpoints. The documentation can be automatically generated from annotations included in the program code. For each endpoint, the API doc describes the structure of both the requests and responses in the grammatical form of a schema that states the names, types, and occurrence constraints of the elements. Example requests and responses can be included.

Conclusion

APIs are an integral part of a web application. They act as connectors between the modules. The most important API is the one that runs on the web server’s backend and provides application data and security for the user interfaces. The backend API is also a single unit of development in a web app project that implements the two-tier client-server architecture. External APIs complement the picture with enabled features or added functionality, though they always come with a price or limitations.



Miro Lehtonen · Project Manager & Lead Developer

Academic scholar with a research focus on information retrieval and web technology, educational and team leader experience at several institutions in Finland, Thailand, and Australia, Miro is currently also an adjunct lecturer at the Mae Fah Luang University, Thailand. He has been applying his academic expertise in a number of different projects at Outsourcify as the IT architect of web portals.

Have a project in mind?
Let's start your project today

Contact Us
Have a project in mind?
Let's start your project today

Related blog articles