What is an API?

The backend architecture actually helps build one of the most common interfaces for consuming data in the software industry: an Application Programming Interface (API). Let’s learn more about the term.

In this course, we’ll primarily be building an API—so, what is an API?

Before answering this question, just remember that most of the internet is powered by Representational State Transfer (REST) or RESTful APIs. An API simplifies the way data is exchanged between applications or machines. It consists mainly of two components:

• The technical specification, which describes the data exchange options between the parties, with the specification made in the form of a request for data delivery protocols and data processing.

• The software interface (the programming code), which is written to the specification that represents it.

For example, if the client side of our application is written in JavaScript and the server side is written in PHP, we’ll need to create a web API with PHP (because data comes from the database), which will help us write the rules and routes that will be used to access data.

Different API protocols

Web APIs are relatively common and there are different specifications and protocols. The goal of API specification is to standardize—because of different programming languages and different Operating Systems (OSs)—exchanges between two or more web services. For example, we’ll find the following:

• Remote Procedure Call (RPC): A protocol that can be used by a program to request a service from a program on another computer on a network that it does not need to know the details of. This is sometimes called a function or subroutine call.

• Simple Object Access Protocol (SOAP): An XML-based communication protocol that allows applications to exchange information with each other over HTTP. It therefore allows access to web services and the interoperability of applications across the web. SOAP is a simple and lightweight protocol that relies entirely on established standards such as HTTP and XML. It is portable and therefore independent of any OS and type of computer. SOAP is a non-proprietary specification.

• REST/RESTful: A style of architecture for building applications (web, intranet, or web service). This is a set of conventions and best practices to be observed, not a technology in its own right. The REST architecture uses the original specifications of the HTTP protocol, rather than reinventing an overlay (like SOAP or XML-RPC do, for example):

  • Rule 1: The URL is a resource identifier

  • Rule 2: HTTP verbs are identifiers of operations

  • Rule 3: HTTP responses are representations of resources

  • Rule 4: Links are relations between resources

  • Rule 5: A parameter is an authentication token

In this course, we’ll be building REST APIs using Django and Django REST, so let’s get to know REST a bit better.

Understanding REST APIs

REST is usually the way to go when developers want to build an API. REST is a simple alternative to SOAP and RPC because it makes it easier to write the logic to access resources. Resources here are represented by a unique URL available with one request to this URL.

RESTful APIs use HTTP requests (or methods) to interact with resources:

• GET: The most commonly used method in APIs and websites. This method is used to retrieve data from a server at a specified resource. This resource is an endpoint returning an object or a list of objects in JSON or XML most of the time.

• POST: This is a basic method for requesting information processing from the server. These requests are supposed to bring mechanisms specific to the server into play and cause communications with other modules, or even other servers, to process said data. Therefore, it is quite likely that two identical POST requests will receive different or even semantically opposite responses. The data to be processed is specified in the body of the request. The document designated by the request via the page is the resource that must process the data and generate the response.

• HEAD: This method is used to query the header of the response without the file being sent to us immediately. This is useful, for example, if large files need to be transferred: thanks to the HEAD request, the client can be informed of the size of the file first and only then decide whether to receive the file.

• OPTIONS: This is a diagnostic method, which returns a message that is useful primarily for debugging and the like. This message basically indicates, surprisingly, which HTTP methods are active on the web server. In reality, it’s rarely used for legitimate purposes these days, but it does give potential hackers a bit of help—it can be seen as a shortcut to finding another hole.

• DELETE and PUT: These methods are supposed to allow a document to be uploaded (to the server) or deleted without going through a File Transfer Protocol (FTP) server or the like. Obviously, this can cause file replacements and, therefore, very large security breaches on a server. Because of this, most web servers require a special configuration with a resource or a document responsible for processing these requests. The document referred to by the request is the one to be replaced (or created), and the content of the document is in the body of the request. In theory, URL parameters and the fragment identifier should be prohibited or ignored by the server. In practice, they are generally transmitted to the resource responsible for processing the request.

• PATCH: This method of an HTTP request applies partial changes to a resource.

• TRACE: This method can be used to trace the path that an HTTP request takes to the server and then to the client.

• CONNECT: This method is supposed to be used to request the use of the server as a proxy. Not all servers necessarily implement them.

One interesting benefit is that RESTful systems support different data formats, such as plain text, HTML, YAML, JSON, and XML.