Lesson 2 - REST API, SOAP, GRAPH, and JSON
In the previous lesson, Introduction to Node.js, we installed and introduced Node. Today we're going to talk about the different types of APIs and the JSON format, which will prepare us for the project we'll be developing in this course.
Project Introduction
In this tutorial, we'll be creating a simple backend API to manage a movie database. We'll be able to add, edit or delete movies, and, of course, view them. APIs are the most common project types in Node.js. We'll access the movie database using a RESTful API, and we'll be using the JSON format... wait, wait, what do all these abbreviations mean?
API
API stands for Application Programming Interface. It's generally anything that allows individual parts of a software to communicate with each other. It's a set of functions and procedures, classes, communication protocols, and other tools. The key is that the communication methods are precisely defined. A programmer who creates a new system component then knows (or can find in the documentation), which procedures he can use to make his component work properly with the other ones.
If you want to think of the API as something of everyday life, imagine a waiter in a restaurant that mediates (and translates) communication between a guest and the chef. Or as a car dashboard that uses precisely defined methods (buttons on the dashboard) to pass what the driver (one component) wants from another component (the engine). And the car instructions from the car manufacturer are like the API documentation, where the various methods (buttons) are described.
There are graphical APIs, framework and library APIs, operating system APIs, but we'll be mainly interested in web APIs.
Web APIs
A web API defines how some components communicate over the Internet. Typically, these are two parts of one application (a website retrieves the necessary data from the server using an AJAX request) or two different applications (a mobile app downloads data from a website). A web service can be a synonym to that. Our web API will allow to perform operations over the movie database, such as searching for an existing movie or inserting a new movie. Of course, web APIs are not limited to databases; we can send SMS through them, check the weather and so on.
A Web API Sample
A small but popular API for e-shops is at https://api.exchangeratesapi.io/latest?…
When you open the link, you will see the exchange rate for the current day. Notice that no HTML page was generated, just raw JSON data. Because web APIs are not intended for people, but for programs. The API output looks like this:
{ "rates":{ "CAD":1.3156479656, "HKD":7.8384119018, "ISK":123.5884567127, "PHP":50.5251837247, "DKK":6.6959132461, "HUF":294.6585409572, "CZK":22.8634163829, "GBP":0.7740455279, "RON":4.2607994264, "SEK":9.5926689371, "IDR":14019.8153791002, "INR":70.7299695286, "BRL":4.0010754616, "RUB":63.2484316186, "HRK":6.675748342, "JPY":108.3796379279, "THB":30.1926868614, "CHF":0.9877218139, "EUR":0.8962179602, "MYR":4.1504749955, "BGN":1.7528230866, "TRY":5.6894604768, "CNY":7.0285893529, "NOK":9.1116687578, "NZD":1.5556551353, "ZAR":14.8141243951, "USD":1.0, "MXN":19.0979566231, "SGD":1.3574117225, "AUD":1.4481089801, "ILS":3.5202545259, "KRW":1162.3229969529, "PLN":3.8168130489 }, "base":"USD", "date":"2019-11-04" }
Types of Web APIs
There are several popular ways of communicating on the Web. These are:
- Simple APIs
- APIs using the SOAP protocol
- APIs using the REST architecture
- Graph API from Facebook
Simple APIs
We've already introduced a simple JSON API with the exchange rate sample. CSV or XML formats can also be used for simple APIs.
Simple APIs typically offer only some data list to download, such as the weather by city, and don't allow more sophisticated data manipulation.
SOAP
SOAP stands for Simple Object Access Protocol. Messages sent using
SOAP are typically XML-based (a markup language similar to HTML). Compared to
REST (see below), SOAP is rather procedural (REST is data-oriented). This is
also reflected in how we call the API - the URL when using SOAP will typically
contain a verb, unlike REST, where there will typically be some noun (in our
case, it will be movies as you'll see later).
A SOAP request would look like this without the long header I left out:
<xs:element name="Body" type="tns:Body"/> <xs:complexType name="Body"> <xs:sequence> <xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:anyAttribute namespace="##other" processContents="lax"/> </xs:complexType> <!-- Global Attributes. The following attributes are intended to be usable via qualified attribute names on any complex type referencing them. --> <xs:attribute name="mustUnderstand" type="xs:boolean" default="0"/> <xs:attribute name="relay" type="xs:boolean" default="0"/> <xs:attribute name="role" type="xs:anyURI"/> <!-- 'encodingStyle' indicates any canonicalization conventions followed in the contents of the containing element. For example, the value 'http://www.w3.org/2003/05/soap-encoding' indicates the pattern described in the SOAP Version 1.2 Part 2: Adjuncts Recommendation --> <xs:attribute name="encodingStyle" type="xs:anyURI"/> <xs:element name="Fault" type="tns:Fault"/> <xs:complexType name="Fault" final="extension"> <xs:annotation> <xs:documentation> Fault reporting structure </xs:documentation> </xs:annotation> <xs:sequence> <xs:element name="Code" type="tns:faultcode"/> <xs:element name="Reason" type="tns:faultreason"/> <xs:element name="Node" type="xs:anyURI" minOccurs="0"/> <xs:element name="Role" type="xs:anyURI" minOccurs="0"/> <xs:element name="Detail" type="tns:detail" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:complexType name="faultreason"> <xs:sequence> <xs:element name="Text" type="tns:reasontext" minOccurs="1" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <xs:complexType name="reasontext"> <xs:simpleContent> <xs:extension base="xs:string"> <xs:attribute ref="xml:lang" use="required"/> </xs:extension> </xs:simpleContent> </xs:complexType> <xs:complexType name="faultcode"> <xs:sequence> <xs:element name="Value" type="tns:faultcodeEnum"/> <xs:element name="Subcode" type="tns:subcode" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:simpleType name="faultcodeEnum"> <xs:restriction base="xs:QName"> <xs:enumeration value="tns:DataEncodingUnknown"/> <xs:enumeration value="tns:MustUnderstand"/> <xs:enumeration value="tns:Receiver"/> <xs:enumeration value="tns:Sender"/> <xs:enumeration value="tns:VersionMismatch"/> </xs:restriction> </xs:simpleType> <xs:complexType name="subcode"> <xs:sequence> <xs:element name="Value" type="xs:QName"/> <xs:element name="Subcode" type="tns:subcode" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:complexType name="detail"> <xs:sequence> <xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> <xs:anyAttribute namespace="##other" processContents="lax"/> </xs:complexType> <!-- Global element declaration and complex type definition for header entry returned due to a mustUnderstand fault --> <xs:element name="NotUnderstood" type="tns:NotUnderstoodType"/> <xs:complexType name="NotUnderstoodType"> <xs:attribute name="qname" type="xs:QName" use="required"/> </xs:complexType> <!-- Global element and associated types for managing version transition as described in Appendix A of the SOAP Version 1.2 Part 1 Recommendation --> <xs:complexType name="SupportedEnvType"> <xs:attribute name="qname" type="xs:QName" use="required"/> </xs:complexType> <xs:element name="Upgrade" type="tns:UpgradeType"/> <xs:complexType name="UpgradeType"> <xs:sequence> <xs:element name="SupportedEnvelope" type="tns:SupportedEnvType" minOccurs="1" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:schema>
Unfortunately, SOAP APIs are not very simple, even though they have the word Simple in their name. Rather, they are used in the state sector and finance for robust projects and are not a frequent choice for classic applications.
REST
REST is currently a very popular interface architecture. It stands for REpresentational State Transfer - a term that Roy Fielding introduced in his dissertation. He is one of the co-authors of the HTTP protocol, so it's not surprising that REST uses this protocol. REST implements four basic CRUD operations. These operations are Create, Read, Update, and Delete. In the HTTP protocol, they are represented by the methods:
- GET (read)
- POST (create)
- PUT (update)
- DELETE
Using different HTTP methods is the basic principle of the REST API. For example, we should not remove data through the classic GET request that we use when we are trying to open a page.
Thanks to these four methods, the REST interface is easy to understand and use. Compared to SOAP, it's much more brief and, therefore, more efficient. Despite its briefness, each request contains all the information needed to handle it, so the server doesn't have to hold any state (it's stateless). It follows, among other things, that if the application needs a state, it must be held by the client.
An API that uses the REST interface is called a RESTful API.
Graph API
To get an idea that there are other application interfaces for communication over the web, let's take a look at the Graph API. It was created and popularized by Facebook, which serves very diverse data through it. Facebook can be asked so many things that the REST or even SOAP requirements would be very confusing. The Graph API uses the concept of social graphs with vertices and edges (as in graph theory) to represent information. Vertices are objects such as a user, photo, page, or comment. The edges are then connections between these objects such as comments below a photo. And the data is stored in objects' fields.
The sample query below asks Facebook about a user's birthday, email, and city:
https://graph.facebook.com/{your-user-id}
?fields=birthday,email,hometown
&access_token={your-user-access-token}
We use the Graph API when it's difficult to formalize our queries, and in each question it's necessary to say exactly what we are interested in.
Our Application's API
We'll use the RESTful API for our application for the reasons mentioned above (simplicity, briefness) and also because we need to perform the operations which it's designed for on our movies. Another reason is that although REST supports many formats, the JSON format is the most popular.
Today we'll talk a little about the JSON format. For the start, I'll mention just that it's suitable for web browsers, and it will be practical for us also because of the database we're going to use - we'll discuss this in one of the next lessons.
When submitting a request using the RESTful API, the correct use of the path
helps us to process the request as we need it. For our first table, which will
include movie data, we'll use the following paths in our app (we'll always
replace id with the appropriate identifier):
POST
For POST request (create, corresponds to the CREATE CRUD method) the address will be:
/api/movies
(no need to enter the movie id, it's about creating an item in the database, the database will create the id itself)
GET
For the GET request (read, corresponds to the READ CRUD method) we'll use this address for all movies:
/api/movies
And for one specific movie:
/api/movies/(id)
PUT
For the PUT request (updating, corresponds to the UPDATE CRUD method) the address will be as follows:
/api/movies/(id)
DELETE
And for the DELETE request (corresponds to the DELETE CRUD method) we'll use this address:
/api/movies/(id)
JSON
I've already mentioned that the RESTful API uses mainly the JSON format. So what is it exactly?
JSON (stands for JavaScript Object Notation) is a format used to store data and communicate on the Web. Although it's based on JavaScript, it's also used by other languages. Its syntax is very similar to the syntax of objects and arrays in JavaScript, with several limitations. Property names must always be in double quotation marks, and only simple data is allowed - no calculations or function calls. Comments are not allowed.
Here's a short demonstration of the JSON format representing a musician, his band and its albums:
[ { "name": "Trent", "last name": "Reznor", "band name": "Nine Inch Nails", "born": 1965, "male": true, "albums": [ "Pretty Hate Machine", "The Downward Spiral", "The Fragile", "With Teeth", "Year Zero", "to be continued..." ] } ]
In the next lesson, Running the project and first lines in Express, we'll explore the Express library. We'll go through creating a new project and implementing the first of the RESTful API methods, the GET method.
