REST API Best Practices REST Endpoint Design Examples

Table Of Content

• Versioning through URI Path
• REST API Design Best Practices Handbook – How to Build a REST API with JavaScript, Node.js, and Express.js
• Other common questions about API design
• Using Gemini Code Assist to build APIs, integrations, and automation flows
• REST API must Accept and Respond with JSON
• #3 Creating “chatty” APIs with too many calls

One appropriate example is to use redis or the express middleware apicache. We defined "workouts" here as a "let" variable because when adding more if-statements for different filters we can overwrite "workouts" and chain the filters. Things like "GET /api/v1/getAllWorkouts" or "DELETE api/v1/deleteWorkout/workoutId" are unnecessary. Using a separate URL for each one might be an overhead (and documentation) hell. As you can see, an error consists of two things, a status and a message. I'm using just the throw keyword here to send out a different data structure than a string, which is required in throw new Error().

Versioning through URI Path

The use case may also have implications on the type of architecture you choose. Once in agreement, stakeholders should clearly outline their goals for the API by describing—in natural language—exactly how it will meet specific needs. When your API endpoint is returning a lot of data like returning a list of users, then using filter, sort, and pagination is a good practice. Just like every other concept in web development, there are always some best practices a developer needs to apply in other to build a web app that satisfies the user experience. If the end user successfully calls the end point with a GET method, the user should obtain the above data along with a 200 response code to validate the correct usage.

REST API Design Best Practices Handbook – How to Build a REST API with JavaScript, Node.js, and Express.js

What Are the Core Principles of Good API Design? - The New Stack

What Are the Core Principles of Good API Design?.

Posted: Thu, 08 Feb 2024 08:00:00 GMT [source]

We've defined some basic metadata of our API, created the docs in JSON format, and created a function that makes our docs available. Let's think a second about a scenario in our API where a cache would make sense. I think requesting to receive all workouts would effectively be served from our cache. You can store this type of data inside your cache and serve it from there instead of going to the database every time to query the data. Using a data cache is also a great practice to improve the overall experience and performance of our API. All we do here is check if we actually have a truthy value for the key "mode" inside our "filterParams".

Other common questions about API design

SmartBear boosts API design with Stoplight tool integration into SwaggerHub - IT Brief New Zealand

SmartBear boosts API design with Stoplight tool integration into SwaggerHub.

Posted: Mon, 22 Apr 2024 21:00:00 GMT [source]

Also, returning a meaningful status code that correctly describes the type of error encountered is essential. “It is responsible for data storage, management and also securing of the data received from the front-end and making sure it is available for the user when needed. When a user sends a request, the backend receives the information, processes it, and sends back a response.” Frontend vs backend.

Using Gemini Code Assist to build APIs, integrations, and automation flows

They allow clients to customize the API response to suit their needs, leading to more efficient data transfer and improved user experience. How can you ensure that your API is flexible, extendable, agile, and accessible to other developers? This section answers this question by demonstrating the value in using nouns – not verbs – as resources, applying CRUD, using JSON, and other best practices.

REST API must Accept and Respond with JSON

These relationships allow you to pull a larger group, or break into that group for a specific item. You also can use PUT to create IDs if the client itself selects the ID number. Frequent deployment of individual APIs can quickly create a software system that resembles an overgrown garden, weed-ridden with bugs, broken integrations and ill-fitted use cases. Bloated collections of APIs make it hard to make changes without causing failures, or even gain the visibility to recognize opportunities for improved functionality. There are many kinds of caching solutions like Redis, in-memory caching, and more. To enforce the principle of least privilege, we need to add role checks either for a single role, or have more granular roles for each user.

Stop guessing about your digital experience with LogRocket

They immediately know to go inside the request body and see if they've missed providing one of the required properties. To improve the experience we also can send a quick error message along with the error response. But as I've written in the introduction this isn't always very wise and should be considered by the engineer themself.

#3 Creating “chatty” APIs with too many calls

Because there were a lot of legacy Swagger documents, it’s important to have a compatible community-owned version. But API practitioners wanted to move the OpenAPI specification forward with OpenAPI v3, with its latest release being 3.1 in 2021. Just like website design or product design, API design informs the user experience. Good API design principles meet initial expectations and continue to behave consistently and predictably. When you make a REST API, you need to help clients (consumers) learn and figure out how to use it correctly. The best way to do this is by providing good documentation for the API.

What is a REST API?

When crafting APIs, the primary design principle should be to maximize application developer productivity and promote adoption. When you make REST APIs available this way, you are not forcing clients to migrate to the new versions in case they choose not to. If this happens, retrieving data from such a database could be very slow.

Web development is not complete if there is no smooth interaction between the client and the server side which makes API design best practices a necessary skill for developers. (If you want to know the difference between PUT and PATCH, check out this feed on StackOverflow.)   Keeping verbs out of your URLs is also a good idea. In the photosharing app, with /users and /photos as end points, an end consumer of your API can easily work with them intuitively using the RESTful CRUD operations described above.

I've created and consumed many API's over the past few years. During that time, I've come across good and bad practices and have experienced nasty situations when consuming and building API's. When you consume a third-party data format that is not JSON, it can be tempting to do straight string manipulation. Instead, if that data is a format such as XML, load the string into a data structure designed to process that format.

To move on in our architecture it would be advisable to create another controller, another service, and another collection of database methods that are responsible for records. Back in our workout controller we receive the return value from workoutService.getAllWorkouts() and simply send it as a response to the client. We've looped the database response through our service to the controller.