API Structure

Let's look at the basic structure of our API.

We'll cover the following

Wikipedia’s definition of application programming interface (API) is essentially the specification of how software components should interact with each other through a common interface. There are other kinds of communication protocols like SOAP, but we are not covering them in this course.

Let’s look at the basic structure of the specific type of API we will be using before we start building it.

Data interchange format

When sharing data with people, the possibilities for displaying the information are limited only by human imagination. The same principle applies when sharing data between computers. One computer has to put the data in a format that the other can understand. So we have to choose a specific data format for our API.

Rails can handle up to 35 different media types. Out of these 35 formats, we are going to be working with JSON.

JSON is an acronym for JavaScript Object Notation, which is a file format that stores data objects in a human-readable form. JSON is widely accepted, readable, extensible, and easy to implement as the Internet media type standard. Many of the current frameworks consume JSON APIs by default, including Angular and Vue.js. There are also great libraries for Objective-C like AFNetworking or RESTKit.

All right, so we have decided that we are building our API with JSON. Now we have to figure out how we will implement this. One option would be to start adding routes to define the endpoints. This approach is likely flawed, though, because they may not have a URI pattern that is clear enough to know which resource is exposed.

API architecture

The protocol we’ll be using instead is REST, which stands for Representational State Transfer. A RESTful API must follow at least three simple guidelines:

  • It has a base URIA Uniform Resource Identifier (URI) is a unique sequence of characters used to identify a resource used by web technologies., such as http://example.com/resources/.

  • It has an internet media type to represent the data - which is commonly JSON - and is set through header exchange.

  • It follows standard HTTP Methods such as GET, POST, PUT and DELETE. These methods are explained as follows:

    ◦ GET reads the resource defined by the URI pattern.

    ◦ POST creates a new entry into the resources collection

    ◦ PUT updates a collection or member of the resources

    ◦ DELETE destroys a collection or member of the resources

The content in this lesson may seem like a lot of information to digest, but don’t worry! The concepts will get easier to understand as we move on with the course.