RU EN
Nov 14, 2022

REST API Naming Conventions and Best Practices

Автор:
Nadin Pethiyagoda
Источник:
Просмотров:
4408
REST API Naming Conventions and Best Practices favorites 0

The main data representation in REST is referred to as a resource. A properly named resource makes an API simple to use and intuitive. That same API, when implemented incorrectly, may feel complicated and be challenging to use and comprehend. The following article will assist you in getting started when constructing the resource URIs for your new API.

Use Nouns to represent resources / Not Verbs

Always make sure that your URIs are named with nouns to specify the resource instead of using verbs. The URIs shouldn’t indicate any CRUD (Create, Read, Update, Delete) operations. Additionally avoid verb-noun combinations: hyphenated, snake_case, camelCase.

Bad examples:

http://api.example.com/v1/store/CreateItems/{item-id}❌
http://api.example.com/v1/store/getEmployees/{emp-id}❌
http://api.example.com/v1/store/update-prices/{price-id}❌
http://api.example.com/v1/store/deleteOrders/{order-id}❌

Good examples:

http://api.example.com/v1/store/items/{item-id}✅
http://api.example.com/v1/store/employees/{emp-id}✅
http://api.example.com/v1/store/prices/{price-id}✅
http://api.example.com/v1/store/orders/{order-id}✅

Use Pluralized Nouns for resources

Use plural when possible unless they are singleton resources.

Bad examples (Typical and Singleton resources):

http://api.example.com/v1/store/item/{item-id}❌
http://api.example.com/v1/store/employee/{emp-id}/address❌

Good examples (Typical and Singleton resources):

http://api.example.com/v1/store/items/{item-id}✅
http://api.example.com/v1/store/employees/{emp-id}/address✅

Use hyphens (-) to improve the readability of URIs

Do not use underscores. Separating words with hyphens will be easy for you and others to interpret. It is more user-friendly when it comes to long-path segmented URIs.

Bad examples:

http://api.example.com/v1/store/vendormanagement/{vendor-id}❌
http://api.example.com/v1/store/itemmanagement/{item-id}/producttype❌
http://api.example.com/v1/store/inventory_management❌

Good examples:

http://api.example.com/v1/store/vendor-management/{vendor-id}✅
http://api.example.com/v1/store/item-management/{item-id}/product-type✅
http://api.example.com/v1/store/inventory-management✅

Use forward slashes (/) for hierarchy but not trailing forward slash (/)

Forward slashes are used to show the hierarchy between individual resources and collections.

Bad example:

http://api.example.com/v1/store/items/❌

Good examples:

http://api.example.com/v1/store/items✅

Avoid using file extensions

They are unnecessary and add length and complexity to URIs.

Bad examples:

http://api.example.com/v1/store/items.json❌
http://api.example.com/v1/store/products.xml❌

Good examples:

http://api.example.com/v1/store/items✅
http://api.example.com/v1/store/products✅

Version your APIs

Always attempt to version your APIs. You can provide an upgrade path without making any fundamental changes to the existing APIs by versioning your APIs. You can also let users know that updated versions of the API are accessible at the following fully-qualified URIs.

http://api.example.com/v1/store/employees/{emp-id}

Introduction in any major breaking update can be avoided with the following /v2.

http://api.example.com/v1/store/items/{item-id}
http://api.example.com/v2/store/employees/{emp-id}/address

Use query component to filter URI collection

You will frequently come into requirements that call for you to sort, filter, or limit a group of resources depending on a particular resource attribute. Instead of creating additional APIs, enable sorting, filtering, and pagination in the resource collection API and give the input parameters as query parameters to meet this requirement.

http://api.example.com/v1/store/items?group=124
http://api.example.com/v1/store/employees?department=IT&region=USA

Examples:

GET — Read employee with employee id 8345

example.com/employees/8345

POST — Create an employee

example.com/employees

PUT — Update employee with employee id 8345

example.com/employees/8345

DELETE — Delete employee with employee id 8345

example.com/employees/8345
Похожее
May 3, 2024
Author: AltexSoft Inc
Imagine that you ask your development team to enable users to search for a product in an online bookstore by category. You expect a straightforward interface with category links to click on (e.g., fantasy, nonfiction, history, etc.) After two weeks...
Feb 17, 2023
Author: Juldhais Hengkyawan
A Guide to Building Scalable, Maintainable Web API using ASP .NET Core The term “Clean Architecture” has become increasingly popular in software development in recent years. Clean Architecture is a software design pattern that prioritizes the separation of concerns, making...
Jun 5, 2023
Author: Juan Alberto España Garcia
In this section, we’ll explore the world of unit testing in C# and .NET, learn what unit testing is, why it’s important, and the landscape of testing frameworks and tools available to developers. What is Unit Testing? Unit testing is...
Aug 22, 2021
The following are a set of best practices for using the HttpClient object in .NET Core when communicating with web APIs. Note that probably not all practices would be recommended in all situations. There can always be good reasons to...
Написать сообщение
Тип
Почта
Имя
*Сообщение
RSS
Если вам понравился этот сайт и вы хотите меня поддержать, вы можете
9 главных трендов в разработке фронтенда в 2024 году
Как мы столкнулись с версионированием и осознали, что вариант «просто проставить цифры» не работает
Переход от монолита к микросервисам: история и практика
14 вопросов об индексах в SQL Server, которые вы стеснялись задать
Performance review, ачивки и погоня за повышением грейда — что может причинить боль сотруднику IT-компании?
Тестирование PRTG Network Monitor и сравнение с Zabbix
Путеводитель по репликации баз данных
Soft skills: 18 самых важных навыков, которыми должен владеть каждый работник
Система визуализации и мониторинга. Grafana + Prometheus
Погружение в 0.0.0.0 Day: как «нулевой» IP-адрес позволяет взломать локальную сеть
Boosty
Donate to support the project
GitHub account
GitHub profile