REST Best Practices - List of simplified entities to populate dropdown-CodePudding

We have a REST API where we have the following rule: when returning a list of entities for a "list entity" use case, we do "GET /entities", returning the required fields.

However, in many cases we need a list of a simplified version of an entity (id and description), for instance to fill a dropdown menu. Is there a "best practice" in this scenario?

Should I use the same "GET /entities" with parameters or should I consider this simplified list as a new resource? In that case (new resource), this resource would be in the same level as the original list (GET /entities-for-dropdown) or could it be a child (GET /entities/dropdown)? Is there another (better) solution?

CodePudding user response：

You have other options, it's up to you to decide if they are better. Here are some in random order:

Limited list results, extensive details
Expose all through list
Use query language such as OData
Use GraphQL or similar query language to quickly tailor your endpoints
Implement custom endpoint tailor made to requirements

I'll elaborate on these below.

Limited list results, extensive details

This is most commonly used - for source check various API/CLI's AWS CLI

GET /entities will return typical things like id's, names, short description and everything you'll typically expect in a short overview.

GET /entities/id, the detailed view retrieves all relevant info for the entity.

Expose all through list

Typically used in scenario's where the details are not very extensive.

Use query language such as OData

Title says it all. It allows for select and expand, an example: http://host/service/Products?$select=Rating,ReleaseDate (See MSDN)

I have people seeing doing an own custom implementation.

Use GraphQL or similar query language to quickly tailor your endpoints

This will provide you with flexibility to change your endpoints according to the use case without altering your underlying API (too much). It is similar to your scenario where you create custom endpoints.

Implement custom endpoint tailor made to requirements

Easy to implement but harder to maintain and change if change occurs frequently.