DEV Community: Dodo Mukunzi

Naming API Routes: Best Practices to Make Your API Intuitive

Dodo Mukunzi — Fri, 10 Mar 2023 11:38:40 +0000

When it comes to building a RESTful API, naming your routes is a critical part of creating a well-designed and easily understood API. In this article, we will explore the best practices for naming RESTful API routes, and look at some common ways people can mess up their API route names. We will also use emojis to make our examples more fun and memorable.

🔑 Best Practices for Naming API Routes

👉 1️⃣ Use Nouns to Represent Resources

One of the most important principles of RESTful API design is to use nouns to represent resources. This means that your routes should describe the things that your API is responsible for managing.

👍 Good:
GET /users: Retrieve a list of users
POST /users: Create a new user
GET /users/:id: Retrieve a specific user

👎 Bad:
GET /get-users: ❌ This route includes a verb that is unnecessary and doesn't describe the resource being managed.

👉 2️⃣ Use Plural Form for Collections and Singular Form for Single Resources

When dealing with collections, it's best to use the plural form for the route. When dealing with a single resource, it's best to use the singular form.

👍 Good:
GET /users: Retrieve a list of users
GET /users/:id: Retrieve a specific user

👎 Bad:
GET /user: ❌ This route doesn't indicate whether it's for a single user or a collection of users.

👉 3️⃣ Use HTTP Methods for Actions

HTTP methods are the primary way to describe what action you want to perform on a resource. You should use them whenever possible, as it makes your API more intuitive to use.

👍 Good:
GET /users: Retrieve a list of users
POST /users: Create a new user
PUT /users/:id: Update a specific user
DELETE /users/:id: Delete a specific user

👎 Bad:
GET /create-user: ❌ This route includes a verb that describes the action being performed, which should be indicated by the HTTP method.

👉 4️⃣ Use Nouns or Adjectives in the Path for Filters or Sorting

Sometimes, you need to filter or sort your data. In these cases, you should use nouns or adjectives in the path to indicate what you're filtering or sorting by.

👍 Good:
GET /users?active=true: Retrieve a list of active users
GET /users?sort=name: Retrieve a list of users sorted by name

👎 Bad:
GET /users/sortByName: ❌ This route includes a verb that describes the action being performed, which should be indicated by the HTTP method.

👉 5️⃣ Use Hyphens to Separate Words in the URL Path

It's a best practice to use hyphens to separate words in your URL path. This makes your URLs more readable and easier to understand.

👍 Good:
GET /user-profile: Retrieve a user profile
POST /post-comment: Create a new comment on a post

👎 Bad:
GET /user_profile: ❌ This route uses underscores instead of hyphens, which can make it harder to read and understand.

In brief, following these five best practices for naming API routes can greatly improve the clarity and intuitiveness of your API design. By using nouns to represent resources, using HTTP methods for actions, and using hyphens to separate words in the URL path, you can make your API easier to understand and use for both developers and end-users. Conversely, violating these best practices can make your API confusing and difficult to work with.

Dynamic RESTful API Design with HATEOAS 🚀

Dodo Mukunzi — Thu, 02 Feb 2023 17:42:24 +0000

Are you tired of constantly having to update your API every time you make changes to your server-side code? 💩 HATEOAS (Hypermedia as the Engine of Application State) is here to save the day!

In this article, we'll dive into what HATEOAS is all about, why it's crucial for RESTful API design, and how to implement it in a Node.js/Express application 🚀.

What is HATEOAS, you ask? 🤔

HATEOAS is a key principle of RESTful architecture that ensures a client interacts with a server-driven application through hypermedia links within resource representations. This means that the client receives a resource representation that includes links to related resources. The client can then dynamically navigate the application's state using these links, without having to hard-code a fixed set of interactions.

Why is HATEOAS Important for RESTful API Design? 🤔

By using HATEOAS, APIs become more flexible, scalable, and maintainable. The client doesn't have to know about all the possible interactions in advance. Instead, it can discover available resources and interact with them dynamically through the hypermedia links provided by the server. This makes updates to the API much easier, as the server can add or remove links without affecting the client.

How to Implement HATEOAS in a Node.js/Express Application 💻

Let's take a look at a simple book library API as an example. First, we'll create a book resource representation that includes hypermedia links. Here's an example of what this could look like:

`{
  "id": 1,
  "title": "To Kill a Mockingbird",
  "author": "Harper Lee",
  "links": [
    {
      "rel": "self",
      "href": "/books/1"
    },
    {
      "rel": "collection",
      "href": "/books"
    }
  ]
}`

In this example, the "self" link points to the current book resource, and the "collection" link points to the collection of all book resources.

Next, we'll create a GET /books/:id endpoint to retrieve a book resource:

app.get('/books/:id', (req, res) => {
  const book = books.find(book => book.id === parseInt(req.params.id));
  if (!book) return res.status(404).send('The book with the given ID was not found.');
  res.send(book);
});`

And that's it! By including hypermedia links within resource representations, clients can dynamically discover available resources and interact with them.

In conclusion, HATEOAS is the missing piece for making RESTful APIs truly dynamic and user-friendly. So, go ahead and add some 🔗 to your API resources – it'll make things easier for your clients and keep your API up-to-date.

As always, happy coding! 💻

View All HTTP Status Codes Offline 😜

Dodo Mukunzi — Fri, 06 Sep 2019 09:28:42 +0000

If you have NodeJS installed just type node in your command line/shell/terminal then type http.STATUS_CODES. All status codes will be returned, just like so:

$ node
> http.STATUS_CODES
{ '100': 'Continue',
  '101': 'Switching Protocols',
  '102': 'Processing',
  '200': 'OK',
  '201': 'Created',
  '202': 'Accepted',
  ... }

Also try http.METHODS just for more fun.

Top 10 Commonly Used HTTP Status Codes

Dodo Mukunzi — Fri, 19 Jul 2019 09:28:09 +0000

HTTP response status codes indicate whether a specific HTTP request has been successfully completed. Responses are grouped into five classes: informational responses, successful responses, redirects, client errors, and server errors.

Here are the 10 commonly used and useful HTTP status codes:

1xx: Informational

None in this class.

2xx: Success

200 OK

It is the general status code. Most common code used to indicate success.
The request has succeeded. The meaning of success varies depending on the HTTP method:
GET: The resource has been fetched and is transmitted in the message body.
HEAD: The entity headers are in the message body.
PUT or POST: The resource describing the result of the action is transmitted in the message body.
TRACE: The message body contains the request message as received by the server

201 Created

Successful creation occurred (via either POST or PUT). Set the Location header to contain a link to the newly-created resource (on POST). Response body content may or may not be present.

204 No Content

Status when wrapped responses are not used and nothing is in the body (e.g. DELETE).

3xx: Redirection

304 Not Modified

This is used for caching purposes. It tells the client that the response has not been modified, so the client can continue to use the same cached version of the response.

4xx: Client Error

400 Bad Request

General error when fulfilling the request would cause an invalid state. Domain validation errors, missing data, etc. are some examples.

401 Unauthorized

The error code response for missing or invalid authentication token.

403 Forbidden

The error code for a user not authorized to perform the operation or the resource is unavailable for some reason (e.g. time constraints, etc.).

404 Not Found

Used when the requested resource is not found, whether it doesn't exist or if there was a 401 or 403 that, for security reasons, the service wants to mask.

409 Conflicts

Whenever a resource conflict would be caused by fulfilling the request. Duplicate entries and deleting root objects when cascade-delete is not supported are a couple of examples.

5xx: Server Error

500 Internal Server Error

The general catch-all error when the server-side throws an exception.