Evolution of a Node.js API, Zoe.js — API
API is a black box which receives requests and gives back responses. It exposes the public interface and hides the underlaying implementation.
API means multiple things, it can be the public interface of a class which are really its public methods, or it can be a Software's public interface. In general it means a Software application. As an API you can think of a weather forecast API, a live soccer goals API or any other application backend.
API stands for Application Programming Interface
From now on we’re talking about Software APIs.
You can call API users as consumers or clients, which have several formats: Web application, Mobile application, another API, a console command (CLI), etc. API specifications help you to design and document your API such as OpenAPI or API Blueprint. A software API can have the best source code in the world, if it doesn’t have a good documentation, it doesn’t worth too much.
There are different types of APIs, like SOAP, JSON-RPC, XML-RPC, REST. RPC stands for Remote Procedure call and it’s great for describing business logics as actions. Zoe.js is built upon the REST (Representational state transfer) architectural style which is great for implementing a CRUD (Cread, Read, Update, Delete) apps. Zoe.js is not a fully REST compatible API, it is not RESTful. For the sake of simplicity and to reduce complexity it's a general API, kind of a RESTlike API.
HTTP
HTTP (Hypertext Transfer Protocol) as a communication protocol, defines the format of the request-response relationship in the client-server model. It’s about sending and receiving web pages, files, data or any resources on the internet. It powers REST APIs great, because HTTP has a URI schema, has a server-client model, it is stateless and cachable. Furthermore, it has HTTP methods and HTTP status codes.
Stateless means that there is no client context stored on the server, between requests.
HTTP messages are human readable. Let’s see an example about requesting the index page of example.com. GET means fetch which is the HTTP method, / is the path or route, HTTP/1.1 is the protocol version. Host: example.com is a header which is an additional information to the request. This request says: I fetch example.com/
GET / HTTP/1.1
Host: example.comThe response starts with the protocol version HTTP/1.1, than 200 is the response status code which means OK. This response has 2 headers, Date and Content-Type. This response says: Everything is OK, response is created at June 13th, the content what you get is HTML, here is the data (body)
HTTP/1.1 200 OK
Date: Sat, 13 Jun 2020 16:44:20 GMT
Content-Type: text/html<html>
<title>
Example Web page
...
HTTP has several methods such as GET for fetching data, POST for sending data (payload) and create something, or DELETE for deleting a specified resource. There are also multiple HTTP status codes for saying what is the status of the response such as 200 means OK, 201 means Created, 400 means Bad Request or 404 means Not Found.
REST API
REST represents data as resources in a specific format, usually JSON or XML. Resources are identified by URIs and there are various actions available on them.
Actions and relationships between resources are discoverable via hypermedia controls (HATEOAS), basically via links. For example an Invoice resource has a pay action which appears as a link on the Invoice resource. Imagine you browse a web page and navigate via HTML links, this is basically the same concept.
REST doesn’t mean HTTP, it can work with any other protocol which fulfills its constraints (client-server model, stateless, etc.).
Resource names with URIs
Resource names should be nouns in plural form. Use lower-case names with underscore or hyphens separators.
To properly represent the invoices in our application invoices URI looks like https://example.com/invoices
In order to identify one specific invoice, I put the invoice identifier behind the resource name /invoices/INV4415
You can have nested resources, but don’t go too deep /invoices/INV4415/items
or
/invoices/INV4415/items/PID77281
Summary
- https://example.com/resource_name/resource_id
- https://example.com/resource_name/resource_id/embedded_resource_name/embedded_resource_id
- https://example.com/resource_name/resource_id/action
HTTP methods in REST
With HTTP methods your request is got a meaning, let’s go over the usual actions.
HTTP response status codes in REST
With HTTP response status codes you can indicate what is the status code of the request.
Article Series
This article (Chapter 4) is part of the Zoe.js article series. Below you can find the Next chapter and all the available Chapters.
Next chapter
Chapters
Adams Academy
theadamsacademy@gmail.com
