API Development
This page is intended to be a guideline for our process of development APIs during the whole project. This page is going to be improved as our general knowledge of API increases.
API is the abbreviation of the Application Programming Interface. APIs are generally used for exchanging data and services among applications. Therefore they act a role as a connector between applications.
The most common analogy of the way APIs work is the Customer-Waiter-Kitchen example. According to this scenario, a customer arrives at a restaurant and orders a meal to the waiter. Then the waiter goes to the kitchen to convey the order and comes back after a while, and serves the meal to the customer. The customer does not need to worry about what is going on in the kitchen. He doesn't need to worry about remaining ingredients or how to cook, either. The kitchen handles those things by the order the waiter conveyed to the kitchen.
In this analogy, the customer and the kitchen are two different applications and the waiter is the API that provides data and service exchange between those two applications.
Customer Application wants some service (the meal) and provides some data (the order) in a well-known format. For instance, the customer has to pick a meal (request) that is present on the menu. Likewise, while providing data to APIs, the data must be in a format that API can understand (ie. a JSON Object). This is why APIs have documents like the menus in the restaurant. You can discover the document of Github API as an example, here.
The waiter (API)conveys the order to the kitchen and after a while, the kitchen prepares the meal (the service) and the waiter delivers the meal to the customer (response).
Likewise, when a client application sends a request using an API, that API fetches the desired data from an endpoint and returns that data to the client as a response.
To conclude, APIs provide a request-response cycle between two applications (order-meal cycle in the customer-kitchen analogy). Therefore, developers can use services they are not experts on.
You can find an advertisement by MuleSoft, describing the waiter analogy.
RESTful API is an architectural style that is a subset of APIs. REST APIs connect the applications on the web and REST is becoming the standard for building web APIs according to here.
The feature making RESTful API that powerful is using the HTTP protocol. While developing an API, the developer must specify the protocol of the API. However, since REST is using HTTP, there is no need to install any additional library.
Also, REST may return the data in the format of YAML, JSON, XML, and others.
Most of the APIs on the web are RESTful APIs.
There are dozens of APIs developed and ready to use on the web. The developer provides you a key and you send requests to the server of that API using that key so that they can understand who is using their service. The main functionality of the key is security and of course to be able to charge users :). Some of them are free or are needed to be purchased or provides limited access for the free version or free for academic purposes, etc..
For example, when you sign up to Google Developer Console that you can find Google APIs, Google gives you 300$ credit for the beginning. After consuming the credit, your account may send a limited amount of query (request) in a certain amount of time (ie. 10 queries per hour). Another example is Twitter API. Once you apply for the developer account they ask you to answer a set of questions and want you to link your Twitter account and then they return you via e-mail after they evaluate your application. You can check the pricing of the Twitter API.
Embedding the API to your project is done by using the document of the API. Every API has its document for this purpose. On the other hand, since most of the APIs using RESTful API style, their format does not vary much, only the content changes.
Here is an example of Google Timezone API. The following example requests the time zone data for Washington, DC, USA, on March 15, 2016, in JSON format:
import requests
timezone_url = 'https://maps.googleapis.com/maps/api/timezone/json?location=38.908133,-77.047119×tamp=1458000000&key=YOUR_API_KEY'
req = requests.request(method = 'GET', url = timezone_url)As you can observe the location values of the request are embedded into the URL but it is not a must. Values can be passed as a parameter to the request function.
url parameter is the URL of the endpoint and we use method = 'GET' since we want to get a response.
req.json() returns something like this:
{
"dstOffset" : 3600,
"rawOffset" : -18000,
"status" : "OK",
"timeZoneId" : "America/New_York",
"timeZoneName" : "Eastern Daylight Time"
}You can check the documentation itself here.
The endpoint is the server-side end of the request-response cycle. Endpoints generally contain a URL and the API sends a request to this URL. The key provided by the developer, generally concatenated to the endpoint URL, but other types of authentications are available, of course.
The URL of the endpoint of the example given above is the timezone_url variable, for instance.
To develop an API, we need a set of tools and a specification(aka. API description language). There are several API description languages. We are going to examine an example.
Open API is a specification for describing an API. Meaning that it is like a programming language. The developer specifies the properties of the API using an API Description Language (aka. specification). You can check the syntax of OpenAPI from Swagger or its own website.
On the other hand, Swagger is a web site providing tools for developing API with OpenAPI. Another example that falls into the same category as Swagger is RAML. RAML has its own specification which is documented here. Similarly, API Blueprint has its own specification called as API Blueprint Language. For further comparison, you can check the slide over here, comparing Swagger and RAML mainly.
APIs are often created before any code is written. ("API First")
The platforms like Swagger, RAML, and API Blueprint provides a blueprint for your API. You specify the functionalities of your API using the specification (API Description Language) of the platform you are developing on (ie. Swagger). Then the platform allows you to export your API as SDK in any programming languages like Java or Python.
Here is a screenshot to analyze:
The developer writes the blueprint of his API using the editor which is in the middle of the screen. The syntax of the blueprint is provided by the specification, which is OpenAPI in this example since we are analyzing the Swagger platform. However, the tools that can be observed at the rest of the screen are provided by the platform, which is Swagger. Swagger renders your blueprint and adds items regarding your design to the interface. Thus, the developer gains much more assistance while designing an API.
Using the extendable menu from the right top called "Export", the developer may convert his design to an SDK written in a programming language like Python, Java, or NodeJS. This process is called Swagger-to-Code. Also, the developer can create a document for his API using export options or dump his API in the JSON format. Those exported types are deployable.
Note: We can refer to another API using $ref tag in the OpenAPI. Link
//TODO