When you are working on a real project, the number of endpoints you will need to design will be higher. You will need a way to remember all your endpoints and the reason they were designed. Similarly, we are confident that documenting software is extremely important for us to remember what a piece of code is supposed to do; API documentation allows us to tell the API consumers how they can use our API by documenting the endpoints and other additional metadata, such as the ones listed:
- Endpoint path
- HTTP verbs
- The expected headers
- The expected body structure
- The expected results
A possible documentation might be just a simple table that contains the data used in the request and responses. For example, the documentation to create a new product might be this:
| Path | Products |
| HTTP method | POST |
| Expected Results | HTTP 200 OK status code |
| Expected Input Headers | Content-type: application/json |
| Expected Input Body | {id: Integer, name: String, price: Decimal} |
| Goal | Use this endpoint to create a new product |
| Authorization | Required Authorization Token |
Having the knowledge of how to design self-explained APIs and how to use HTTP to create endpoints, let's move forward to implement a RESTful API with Node.js.