What is an API?
API stands for “Application Programming Interface”. An API is an interface that allows other software applications to interact with your software application. You are the publisher of the API, the other parties are consumers of your API. Other applications consume your API, e.g. to read data or to send data. An API is to software, what a UI is to humans.
Similar to the UI of a web application, API’s also use HTTPS as a communication channel. An API consists of URL’s that are called endpoints. Each URL or endpoint typically has one specific function, e.g. it provides a list of customers. Another URL will provide a different function, e.g. the creation of a new customer.
Obviously, for security reasons API’s use HTTPS and not HTTP. When using HTTPS, all communication between the consumer (the client) and the server is encrypted, to make sure that nobody can read the data that is sent back and forth while it travels the internet.
Introduction to the HTTP(S) protocol
In order to better understand how API’s work, we need to understand how web pages are delivered over the internet first. When you type in a URL in your browser to visit a webpage, your browser will use the HTTP(S) protocol to communicate with the server that hosts the website. The HTTP(S) protocol works with a request-response principle.
HTTP(S) requests can use different methods. The most common method is the “GET” method, it is used to get a webpage for viewing. The second most common method is “POST”, it is used to post information from the client (the browser) to the server. When you fill in a form on a webpage and click on the Submit page, your browser will do a “POST” request to the server, and send the information that you filled in, in the body part of the request. Other methods that exist include PUT, PATCH, DELETE and there are others.
The server will send an HTTP response to the client (the browser). The response typically includes HTML of the webpage that was requested. As part of the response, a status code will also be sent back to the client. When everything goes well, the status code will be 200, which means “OK”. But the status code can also be 301 when the webpage was moved to another location (this is called a redirect), or the status can be 401 when you don’t have access to the webpage, or e.g. 500 when an error occurred on the server.
Note that HTTPS works in an identical manner to HTTP, except that the data is encrypted before the request is sent, it is decrypted by the receiving server, and vice versa for the response. The encryption is done using a so called private key. The decryption is done using a public key. The public and private key are part of an SSL certificate, and an SSL certificate can be purchased online.
Now back to API’s: modern API’s are REST API’s, which means they follow a certain number of rules. The bottom line is that these REST API’s are simple to use, easy to understand and that they have a logical structure. Guess what, REST API’s use the same HTTP(S) protocol as webpages, they use the same methods (GET, POST, PUT etc.) as we discussed before and they use the same response codes (200, 301, 400 etc.). The only difference is that the response that the API server sends to the client is not a webpage (which is in HTML). Instead, an API server returns data, typically in the JSON format.
SOAP VS REST API
Over 10 years ago, API’s were mostly implemented using the “SOAP Webservices” standard, with XML as the data format. While SOAP has its value in an enterprise context, it turns out to be a rather complex standard, and that’s why REST was invented. SOAP Webservices are still in use today, for example Salesforce and Marketo have both SOAP Webservices and REST API’s. However, most SaaS companies today, choose to publish only REST API’s, using JSON as the data format.