RESTful API Best Practices

If youre involved in API design these days it can feel like someone is proclaiming the benefits of RESTful API design everywhere you turn. However, that advice often comes without an explanation of exactly what is meant by RESTful APIs or is mixed in with advice that isnt so much about API design as it is about the implementation in the code of a specific framework or language.

In this article, were going to walk through a brief origin of RESTful APIs and then take a good look at what to consider when building your own APIs with RESTful design.

What is a RESTful API?

REpresentational State Transfer or REST is an architectural pattern designed by Roy Fielding, in a chapter of the dissertation he wrote in 2000. Fielding had been involved in the development of a number of standards for the early internet.

He saw that patterns were arising in the design of communication protocols between different applications that would have significant performance and usability issues as the fledgling internet began to take off. In particular, he came up with six architectural constraints for building an API that would be well suited to the internet age.

Shortly after the publication of Fieldings dissertation, developers began making intentional use of these principles that hed definedin ways that would make their systems easier to use and implement. Since not all of Fieldings constraints were seen as necessary for a particular application, people began referring to RESTful APIs as a way to distinguish between the theory and implementation of the pattern.

Over time, various web frameworks began to bake the principles of RESTful API design into their tooling and made it more straightforward for API developers to build well-designed application interfaces.

Good Design Matters

While some development frameworks are oriented toward RESTful design, RESTful API development requires planning for how your application will be built. An API designed according to the principles of REST can be built on any platform. These days, RESTful design revolves around four major design ideas. Let's take a look at each of them.

1. Use native HTTP methods.

Possibly the most universal aspect of any RESTful API is the decision to make use of HTTP methods for their defined purposes. If you need to retrieve information from an API, use GET. If you need to create a new resource, POST the representation of your resource to the API.

PUT and PATCH should be used to update existing resources either in their entirety or in part. DELETE is the right method, as you may guess, to delete a resource.

2. Make your endpoints descriptive.

Another important piece of RESTful design is to make the URL endpoints of your API descriptive of the things they work with. The /accounts endpoint should provide information about accounts whose records are stored in the application when sent a GET request, and a new account should be created when a valid representation of an account is POSTed to it.

This isn't to say that every API designed with RESTful principles needs an account system, but rather that it should be easily intuited what a developer might experience when interacting with a particular endpoint.

3. Provide parameters and good defaults.

While not essential to Fielding's conception of REST, a very commonand often expectedaspect of RESTful APIs today is the ability to filter, paginate, sort, or otherwise manipulate the data returned from an API. This is done with query parameters or custom headers. This sort of design decision helps with the adoption of your APIs, as it clarifies and simplifies the work of any developer hoping to consume your API.

4. Prioritize readable responses.

Another item that makes RESTful APIs a joy to use is an emphasis on readable responses and request bodies. While RESTful design doesn't require the use of a particular markup language or notation, the overwhelming majority of cases today use JSON. In fact, RESTful design is often seen as synonymous with the use of JSON.

Of course, you could continue to use XML or any other text-based communication method. However, if you advertise a RESTful API, it's important to make sure the data is easily accessibleboth for the systems ingesting it and the humans building those systems. The lightweight syntax of JSON makes this particularly easy, which is why it's often preferred.

Discoverability and Documentation

Following these principles of API design can certainly help with creating a usable API. However, alone they aren't enough to make sure your API is well adopted by developers interacting with it. Even though readability and intuitive navigation of your system is implied with RESTful design, it's important to make sure you provide great documentation as well.

The use of standard definitions such as OpenAPI can make your application much easier for developers to learn. Following good design practices also makes it easier to adopt readily available tools for writing your documentation. Be sure to lean into the virtuous cycle created by these tools and design principles.

Manage Change with API Versions

Even though delivering constant updates to your applications is likely, it's important to be careful about the changes you make to the design of your API. How one might indicate versions is a matter of debate, but what's not in question is that an API should have an indicator of what version a developer is using.

Whether developers access different versions of your API via the URL route, custom headers, or some other method, you should make sure your documentation is also versioned to match what they'll experience with each version of the API.

• There's also no canonical method of determining version numbers, but Semantic Versioning (SemVer) is a frequently used numbering style that can be applied to API design just as much as to packaged software. SemVer dictates a version number of the format MAJOR.MINOR.PATCH. Here:The MAJOR number indicates versions that have breaking changes between them.

• A MINOR number indicates new functionality added in a backward-compatible format as numbers increment.
• Lastly, a PATCH number indicates bug fixes that add no new functionality.

Whether you use SemVer or just include a path to your v1 or v2 APIs, don't forget to version your API. It'll save people a lot of headaches as you improve and change your application.

Build with Security in Mind

Many aspects of API security are what you'd expect for any web application. Make sure to encrypt any traffic to your application with SSL/TLS. Require both API authentication and authorization to scope the data you're sharing with your clients so they only see or change what they're supposed to.

However, there are some aspects of API security that you might not think of when designing a standard web application. For example, a common mistake is to send authentication information as a URL query parameter or, even worse, in the actual URL path. The more secure alternative is to include authentication information in HTTP headers, which are unlikely to be logged, stored in browser history, or intercepted by middlemen (whether by accident or on purpose).

That said, it's still important to make sure you don't expose more information than you want to reveal in your headers or error messages. It can present a security risk to expose the language, framework, or web server that you're serving your application through. Some systems include these details by default in their responses, so make sure the things you're exposing in responses make sense for the environment in which they're being sent.

Practice Graceful Error handling

Just like with HTTP request methods, it's important to make sure you use HTTP response codes properly. Any developer consuming your API will expector at least hopeto see more than just a plain 200, 400, or 500 response.

Make sure the responses your application provides are enough for developers to know how to proceed as they build out great client applications for interacting with your system. This means including other information that may be helpful for troubleshooting any errors they run into as their applications interact with yours.

Conclusion

Remember, building a great RESTful API depends much more on the thought you put into the application design rather than on the implementation details. If you make sure your API is easy to discover and understand, that it uses standard HTTP methods and responses, and is well documented, then you will improve your chances of gaining wide adoption by developers hoping to build cool things based on your systems.

In case you're interested in learning more about RESTful APIs, be sure to check back later for an upcoming RESTful API tutorial!