RESTful APIs with NodeJS. An Introductory Course for Prospective DBooks Contributors

Repository

https://github.com/feekayo/dbooks-api

What will I learn

1. You will learn what REST architectural style is
2. You will learn the intricacies of RESTful APIs and what makes them RESTful
3. You will learn the HTTP verbs and their usage
4. You will learn HTTP Status codes and their meanings
5. You will learn how to name resources and interact with said resource
6. You will see how to create a simple endpoint on the DBooks API using NodeJS

Requirements

1. Dbooks-api
2. NodeJS
3. ExpressJS
4. Basic knowledge of NodeJS
5. Any Suitable code editor

Difficulty

1. Intermediate

Tutorial Content

This is the first tutorial in a series aimed at providing would be Dbooks.org Contributors with a means of jumping right in to the application source code and providing new functionality without too much ado.

In this tutorial we would be covering the concept of RESTful APIs, what they entail, their methods, rules and inner workings; We would round everything up by setting up a basic RESTful endpoint with NodeJS on the dbooks-api repository. This endpoint would be a RESTful resource that we can be use to communicate with client devices (web, desktop and mobile).

How to Setup Dbooks-api

Setting up the dbooks-api on your local device has been covered in the Readme.md of the Dbooks-api repository. But let do a brief recap

1. Download or clone the dbooks api repository
2. From the dbooks-api root directory, run npm install
3. After installation. Run node app.js

Now Let's get started

What are RESTful web services

REST stands for Representational State Transfer, which according to Wikipedia is an architectural style that defines a set of constraints to be used for creating Web Services.

Web services that meet these constraints are called RESTful web services and they provide interoperability between computer systems on the internet.

This simply means that regardless of the states or contexts of execution of client devices, they would all share the same and equal ability to enjoy these web resources.

There are six constraints a web Service must meet to be considered RESTful, these include

1. Client-Server Architecture :- There must be a separation of concerns between the client and the server. This helps separate concerns like user interfacing from data storage and improves the ability to implement user interfaces across multiple platforms
2. Uniform interface:- All clients, regardless of platform type or context of executions must have access to the same interface. A good example of this is the ability of Android and IOS implementations of the same applications to share the same web services
3. Statelessness:- No client context is stored on the server between requests, and a session state is saved by the client. The RESTful resource has no idea what a request entails till it allows it through.
4. Cacheability:- Responses from RESTful services are must be cacheable, in cases where some of these responses are repetitive
5. Layered System:- This allows for scalability, RESTful web services must be allowed the ability to possess intermediary servers which enable load balancing, shared caches and even enforce security policies
6. Code on demand (optional):- Servers can temporarily allow functionality of a client to be extended by transferring executable code to the client. This means that from the server, you could tweak certain functionality of the Client.

Quick Tips for RESTful APIs

1. Use HTTP verbs to give your requests meaning

API consumers use HTTP verbs to understand the context of operation of API resources. These consumers/clients send requests with HTTP verbs, these HTTP verbs include

GET
Generally used to read a specific resource by a specific identifier or a collection of resources

PUT
Generally used to update a specific resource by a specific resource identifier

DELETE
Generally used to delete a specific resource by a specific resource identifier

POST
Generally used to create a new resource. They are also mostly used for all other operations that don’t fit into the other categories

2. Provide Sensible Resource Names

Let your resource names be easily readable and understandable to even the most untrained eyes. This makes it easy for your APIs to be easily understandable by someone who is not familiar with your API and its inner workings
Here are some quick rules for creating resource paths (URL paths)

1. Use identifiers in urls rather than in the query string
2. Leverage hierarchical nature of the URL to imply structure
3. Design for your clients not for your data
4. Resource names should be nouns not verbs
5. Use plurals in URL segments to keep your API URLs consistent across all HTTP methods
6. Use lowercase in UR segments, separating words with underscores or hyphens
7. Keep URLs as short as possible, with as few segments as makes sense

3. Use HTTP response codes to Indicate Status

HTTP Response status codes are used to communicate server statuses post execution. There are quite a number of status codes. They include

1. 200 OK:- General success status code. Most commonly used code, used to indicate success
2. 201 Created:- Used to indicate success in creating via PUT or POST
3. 204 No Content:- Indicate success, but with nothing in response body
4. 400 Bad Request:- General Error
5. 401 Unauthorized:- Invalid authentication token
6. 403 Forbidden:- Forbidden request
7. 405 Method Not Allowed:- requested URL exists, but you’re not allowed access to it
8. 409 Conflict:- Caused when a request in a resource conflict
9. 500 Internal Server Error:- General Error

Thanks for following the tutorial. Questions would be entertained in the comment section

Curriculum

N/A

Proof of Work Done

https://github.com/feekayo