Creating Resources in Your REST API - Best Practices and Guidelines

In this article, we will dive into the nuances of creating resources in a REST API. We will cover the architectural choices, guidelines, and best practices you should follow while creating endpoints for your REST API. We will begin by discussing how to create resources in your API, which involves creating HTTP POST endpoints. We will then move on to more nuanced details of creating resources in your API.

Creating Resources in Your REST API

Up until this point, you may have been using an in-memory list of items, which is only being initialized once with a controller, and then populated with some posts. However, creating a resource in your REST API requires much more than just simple reads. It involves making certain architectural choices, which are critical for creating endpoints.

You can create a new endpoint in your API, which involves HTTP POST. You will make an API create endpoint, using the exact same path as you get old. This is because, when you create something against a specific collection of resources, you name your endpoints that way.

We will make this endpoint public, and the result will be the implicitly created method. You don't need to specify what you're creating because in the routes, it's coming down from the class. The controller is coming down from the posts' controller name.

All you need to do is read a post and then save it; for this, you can use the "create post" method. Use the "from body" attribute in the function to read what comes in. This tells the API that there's a post request coming and that there's a body in this request. The API must map this body to some object so that it can be used.

Once this is done, you'll get a post from the user and save it in the database. In this case, we're storing it in memory. Finally, return the created post. But hold on, there are a few more things you need to consider before you can successfully create a resource in your API.

Guidelines to follow while Creating Resources

To properly create a resource in your REST API, you must adhere to the following guidelines:

1. Use Contracts Instead of Domain Objects to read requests: Using domain objects to read the contract is not recommended. Instead, use contracts to map requests to domain objects. Create a folder in your project for contracts. Make sure to separate your contracts and domain objects in your codes.

2. Use Versioned Responses: The consumer always gets the same object, which is versioned. For that reason, ensure that the response should also be versioned. If you add something new, it must not break anyone.

3. Do not mix your Contracts with Domain Objects: It is crucial to separate your domain objects in memory from your in-memory-application objects. They should be completely different and not mixed up.

4. Return a structured response: You should not return the domain object directly; instead, make another object called a response object. It should also be versioned for the sake of consistency.

5. Return Location Header: Always provide a location header for the created items. The location header is a header that specifies where the results you just created will be located.

Adding Location Headers to Response

After creating your created item, you cannot merely say 201: created; you must also provide the location header, specifying where the items created can be retrieved, as this is the exact intent of creating an HTTP POST.

Consider the following steps to add the location headers in your REST API:

1. Add your "posts" thing and check if the post ID is not empty. If the string is non-empty, then post.id = P or D.

2. Instead of using a hack, call the keyword "base" in your URL to have a coherent base URL.

3. Concatenate two parts of the base URL: Source and Destination. Use F-Strings to quickly create your URL from both strings easily.

After these steps, you should get a new endpoint, which is a post created. It explains to you what you need to have in the body. The user can specify IDs at this stage, although normally you wouldn't do that.

Best Practices for Creating Resources

Follow the upcoming best practices while creating resources in your REST API:

1. Always version the contracts you expose to users. Any changes you make to the contract must be backward compatible.

2. Make sure that your APIs use a standardized and versioned URL structure.

3. Use query parameters for filtering, sorting, and pagination.

4. Use a "delete flag" instead of deleting the record. You can implement this by adding an additional boolean flag to your data object. This allows you to "soft-delete" the record instead of deleting it from your database.

Conclusion

Creating resources in your REST API requires a lot of attention to detail, architecture, guidelines, and best practices. We have provided an overview of how to create resources in your API, and we have also mentioned the architectural choices and guidelines you should follow. Moreover, best practices must be observed to avoid errors and provide the best user experience. Follow these guidelines and best practices for creating resources in your REST API, and you'll be well on your way to success.