DEV Community: Thiago

Master your API: Naming conventions

Thiago — Mon, 01 Jul 2024 19:08:56 +0000

Naming things is probably the most common thing a developer does.

Naming your API properly is essential to provide clarity and facilitate its usage. Let’s see some best practices for naming REST APIs.

Tips

Define good resources

The resource represents the data or functionality exposed by the API and is typically identified by unique URIs (Uniform Resource Identifiers).

When we are talking about REST API defining good resources is essential to avoid confusing APIs.

❌ /data -> This endpoint can be a little confusing, it is important to define clear resource names.

✅ /products -> Now is much easier to undestand what is the goal of this resource

Note: Having deep knowledge of the domain can help a lot in defining good name for the resources.

Use noun

The resources are described by nouns, you should not use verbs. Using verbs goes against the RESTful architectural style, which emphasizes using HTTP methods to represent actions on resources.

❌ /createUser

✅ /users

Use plural

Use plural for the resource name, this is more aligned with RESTful best practices, as we can have a single resource URI that can return a list or a single element.

❌ /user

✅ /users

Use Hyphens for resources

The name of the resource should follow the name conventional from RFC1738. Using Hyphens improves the readability.

“Scheme names consist of a sequence of characters. The lower case letters "a"--"z", digits, and the characters plus ("+"), period ("."), and hyphen ("-") are allowed…”

RC1738

To make your URIs easy for people to scan and interpret, use the hyphen (-) character to improve the readability of names in long path segments. Anywhere you would use a space or hyphen in English, you should use a hyphen in a URI

REST API Design Rulebook - Mark Masse's

❌ /users/profileSettings

✅ /users/profile-settings

Keep a standard for query parameters

If your API has pagination or a common standard for filter, apply the same query parameter for all endpoints that make sense to have it. This makes your API easier to use and understand.

❌ /users?size=3&page_numer=0
   /products?limit=3&offset=0

✅ /users?page=2&limit=10
   /products?page=0&limit=10

Many guidelines recommend using hyphens for query parameters, while others suggest using camel case. The most important thing is to follow a convention and ensure that this standard is maintained throughout your entire API.

❌ /users/{user_id}
   /products/{productId}

✅ /users/{userId}
   /products/{productId}

Hierarchical URI Structure

Using Hierarchical URI is essential to provide a clean REST API, but it should be used properly to avoid complex hierarchy resources.

❌ /products-categories

✅ /products/categories

In case you have a complex hierarchy, with a long chain of nested resources, it can become a problem to use and maintain. In this case, separating the resources can be a better approach.

❌/products/{productId}/categories/{categoryid}/reviews/{reviewId}/comments

✅ /reviews/{reviewId}/comments?productId=?&categoryId=?

Conclusion

We’ve seen many good practices related to naming conventional for REST API.

By following these practices, you guarantee an API easier to use as it is more readable and follows the market standard. Not only that, but your API will also be easier to maintain and involve.

I hope these tips have been useful to you, and if you know any other tips related to conventional nomenclature, share them here.

References

Azure Naming Guidelines

Swagger - Best Practices in API Design

Zalando - RESTful API and Event Guidelines

REST API Design Rulebook - Mark Masse's

Versioning Your REST API Made Easy: Tips and Tricks

Thiago — Tue, 14 May 2024 11:10:00 +0000

Before we start, let’s talk a little bit about what is an API REST and why we should be careful about versioning.

Versioning REST API

When you have an API that multiple applications can consume, you should strongly consider using versioning on your APIs.

Example 1:

Let’s consider that your API is for a mobile application. If you do not support more than one version of your API, you will obligate the users to keep up with the latest version. In the case of a mobile app, this can be a bit annoying.

Example 2:

Let’s consider that your API is consumed for more than one service.

For example, you create a payment API that is used for more than one microservice. In this case, if you do not use versioning, it may cause break changes in all consumers.

This is why versioning your API is so important, by doing it, you can ensure that old consumers can still consume your API and have time to migrate to the latest version before it becomes unavailable.

Versioning Strategies

There is more than one way to version your REST API, let’s see some strategies and the advantages and disadvantages of each one.

URI

Advantages

Clear and Explicit: Version numbers are directly visible in the URI, making it clear and explicit which version of the API is being accessed.
Caching: URI versioning can leverage HTTP caching mechanisms effectively, as different versions of the API are treated as separate resources.
Bookmarking: Consumers can bookmark specific versions of endpoints for future reference or sharing.

Disadvantages

Pollution of URIs: Over time, URI versioning can lead to cluttered URIs, especially if multiple versions of the API are maintained simultaneously.
Hard to Change: Once a version is included in the URI, it becomes part of the API's public contract and is difficult to change without breaking backward compatibility.

Example

Twitter/X API: Twitter's REST API utilizes URI versioning by incorporating the API version number directly into the URI path. For example, https://api.twitter.com/1.1/statuses/user_timeline.json represents version 1.1 of the API.
YouTube API utilizes URI versioning, allowing the clients to specify the API version using the “v” URI path. For example: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY&part=snippet,contentDetails,statistics,status this represents the version v3.

Header

Advantages

Clean URIs: Versioning information is not included in the URI path, keeping URIs clean and focused on resource identification.
Flexibility: Header versioning allows for more flexibility in API design, as version information is separate from the resource representation.
Version Negotiation: Clients can negotiate the desired API version using HTTP headers, allowing for dynamic version selection based on client preferences or capabilities.

Disadvantages

Less Discoverable: Versioning information is not directly visible in the request URI, which may make it less discoverable for developers.
Dependency on Headers: Clients must include version information in request headers, which may require additional configuration or code changes.

Example

GitHub API: The GitHub API supports header versioning. Clients can specify the desired API version using the X-GitHub-Api-Version header in HTTP requests. For example, X-GitHub-Api-Version:2022-11-28 indicates the version released on date 2022-11-28 of the GitHub API.
Stripe API: Stripe's REST API allows clients to specify the API version using the Stripe-Version header in HTTP requests. This approach allows Stripe to introduce breaking changes in newer versions without impacting existing integrations.

Query Parameter

Advantages

Non-Intrusive: Versioning information is included as a query parameter, which is non-intrusive and does not clutter the URI path.
Easy to Implement: Adding version information as a query parameter is straightforward and does not require significant changes to existing API endpoints.

Disadvantages

Caching Challenges: Query parameter versioning can lead to caching challenges, as different versions of the same resource may be cached separately.
Potential for Complexity: Handling versioning logic in query parameters can introduce complexity, especially for complex APIs with numerous endpoints.
Discoverability: Versioning information is not directly visible in the URI path, which may impact discoverability for developers exploring the API.

Example

Google Cloud Translation API: this API utilizes query parameter versioning for the discovery service, where clients can specify the API version using the v query parameter. For example, https://translate.googleapis.com/$discovery/rest?version=v3 indicates version 3 of this API.

Conclusion

There are many ways to version your REST API, the most famous is using URI and Header, it is essential to decide on one way and keep it clear for the consumers.

It is also important to keep your documentation up to date and notify consumers that a new version exists, as well as the deadline for removing the old version, giving consumers enough time to update to the latest version.

I hope this can help you guarantee that your APIs are backward compatible.

If this helped you, subscribe to continue receiving more useful content 😊

References

5 Things I wanted to know about REST API when I was starting

Thiago — Sun, 05 May 2024 16:07:33 +0000

What is a REST API?

API (Application Programming Interface) is a set of routines, protocols, and tools for building software applications.

REST (Representational state transfer) is an architectural style for distributed hypermedia systems. It was introduced in 2000 by Roy Fielding in his dissertation.

So, a REST API or a RESTFul API is an API that implements the REST principles.

1. RFC what is it?

RFC stands for "Request for Comments." An RFC is a document that describes various aspects of the design, specifications, and working of the internet and internet-related systems.

In the context of computer networking and the Internet, an RFC is a type of publication from the Internet Engineering Task Force (IETF) and the Internet Society (ISOC). The RFC documents contain technical specifications and organizational notes for the Internet.

To know more about RFC access: https://www.ietf.org/standards/rfcs/

There are some RFCs that were created to deal with REST, the first one was RFC 2616 created in June 1999 and became obsolete by RFC7230 - RFC7235 created in June 2014, and now these RFCs are also obsolete because of the new RFC9110, RFC9111 and RFC9112 that were created in June 2022.

2. What are the most common HTTP Methods?

For more information, access RFC9110 - HTTP Methods

3. What is idempotent?

An operation is considered idempotent if performing it multiple times has the same effect as performing it once. In other words, no matter how many times you repeat the operation, the system's state remains consistent. This property is crucial for the reliability and predictability of RESTful services.

Benefits of Idempotence:

Predictable Behavior: Developers can rely on the fact that repeating an idempotent operation won't cause unexpected side effects.
Retry Mechanisms: Idempotence is useful for designing reliable systems. If a request fails, it can be safely retried without causing unintended changes.

4. What are the most common HTTP Statuses?

1xx (Informational): The request was received, continuing process
2xx (Successful): The request was successfully received, understood, and accepted
3xx (Redirection): Further action needs to be taken in order to complete the request
4xx (Client Error): The request contains bad syntax or cannot be fulfilled
5xx (Server Error): The server failed to fulfill an apparently valid request

These are some common HTTP Status:

It's crucial to know the most common HTTP status codes, as there are over 30 of them. Start by mastering the most common ones to gain a solid foundation in web development.

To know more about the HTTP status, access the RFC9110 - Status Codes

5. What is the Glory of REST?

Leonard Richardson breaks down the principal elements of a REST approach into three steps:

Level 0 (The Swap of POX): At this level there is only one endpoint, and normally it doesn't use HTTP Status, so the API will return 200 OK on all types of responses and the output will contain the error. At this level there is a single HTTP Method, usually POST.
Level 1 (Resources): At this level it will be more than one endpoint, actually one endpoint per resource, but still not using the HTTP Verbs or HTTP Status.
Level 2 (HTTP Verbs): At this level will use the HTTP Verbs and the HTTP Status
Level 3 (Hypermedia Controls): This is the most mature level of Richardson’s model, in this level the API will use HATEOAS(Hypermedia as the Engine of Application State), which encourages easy discoverability.

If you want to know more about it, read these articles:

Conclusion

To write a wonderful API, you must know RFC and best practices. This will help you create an API that follows the common standard, then it will be easy to be a customer of your API.

Another important thing is to define a REST API design. It will be easier to use your API if you have some well-known design. Try searching for famous APIs and see how they are designed to understand how to do this and what are the best practices.

Now you know what is an API and what is a REST API, but what I showed here is just the basics concepts, so keep studying 😊

References:

REST API - Design Rulebook - Mark Masse
AZURE API Guidelines
Best practices for REST API design - Stackoverflow Blog
Swagger specification
RESTFUL API
Stripe API Design