REST API Endpoint, Resources, Action
Endpoints
To invoke a REST AP you need an endpoint or url.
A url consists of multiple parts.
Best Practice
- Avoid www domain
- keep your base URL simple (host+port+application context). Easy to remember
- If possible use a subdomain (for instance api.yourdomain.com)
Resources
Don’t use verb but just resource name. For instance, don’t use /getItems but simply /items
Specify resource name as plural
Actions
Actions are operation that we ask the system to perform, but they are not CRUD.
/estimates or /buy or /print and so on.
They are mainly POST and PUT, but we may have GET for search actions followed by the parameters for the search
Associations
Associations are resources that contain other resources.
In these cases the rest endpoint could be nested. For example
/items/{id} returns the item details, and /items{id}/reviews or items{id}/photos to return other resources contained in the main item resource
To get a single resource contained in another resource the we will add as last parameter the id of the subresource. For instance items{id}/photos/{idPhoto}
Avoid deep nesting, let’s say 3 levels