Web Services v1 Best Practices
This section is an overview on do’s and don’ts when creating your web service calls
For Hivedome
Nouns not verbs (the verbs are the HTTP requests).
- Good: GET /Contracts
- Bad: GET /GetAllContracts
Keep Wording Short
- Bad: GET /Contracts/FuturesAndOptions/
- Good: GET /Contracts/FandO/
GET methods and query parameters never alter the state.
- GET /Contracts/P00001.001?update – not allowed
- GET /Contracts/P00001.001/update – not allowed
- PUT /Contracts/P00001.001 – ok
Nest sub resources in lower URIs
- GET /Contracts/Physicals/ returns all physical contracts
Versioning
- Versioning will be included to the header section of each response.
- Clients can call specific versions of services by adding the version number of the service they wish to call in the request Header.
- If version number is not included in the request the most recent version will be used for the response.
Please Note: Versioning will be available in early 2015.
Bulk updates not currently supported
- PUT /Contracts/Physicals – not allowed
- PUT /Contracts/Physicals?ConID=P10000.110 – ok
Don’t allow DELETE (for now!)
URL encode URIs
- /Contracts/Physicals/P10000.000 – will error
- /Contracts/Physicals/P10000%2E000 – returns contract P10000.000
Do allow multiple endpoints
- GET /Contracts/Physicals – gets all physical contracts
- GET /Contracts/Physicals/P10000.110 – gets a specific contract
- POST /Contracts/Physicals – creates a new contract
- POST /Contracts/Physicals/P10000.110
Paging
Use limit and offset. It is flexible for the user and common in leading databases. The default should be limit=20 and offset=0
GET /cars?offset=10&limit=5
To send the total entries back to the user use the custom HTTP header: X-Total-Count.
Links to the next or previous page should be provided in the HTTP header link as well. It is important to follow this link header values instead of constructing your own URLs.
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=15&limit=5>; rel="next",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=50&limit=3>; rel="last",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=0&limit=5>; rel="first",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=5&limit=5>; rel="prev",
Result Filtering and Sorting
As a rule filters and sorting can be applied to returned results via query parameters. Unary negatives can be used to sort descending.
Examples:
GET /cars?sort=-manufactorer,+model (This returns a list of cars sorted by descending manufacturers and ascending models.)
GET /cars?color=red (Returns a list of red cars)
GET /cars?seats<=2 (Returns a list of cars with a maximum of 2 seats)
Input Validation – Hivedome web services are built on the principal that it is more efficient to validate an input value before it is sent to the downstream systems therefore Hivedome always endeavour to check values and data types at the web services input layer. Data validation includes: data type, required values and max length.
Further validation takes place in the business logic layer though this usually more complex and will include checking different fields against each other as well as conditional mandatory fields.
For Clients
URL encode URIs
- /Contracts/Physicals/P10000.000 – will error
- /Contracts/Physicals/P10000%2E000 – returns contract P10000.000
Always use plural nouns.
- /Contracts/Physicals/P10000.000 – returns a specific contract
- /Contracts/Physicals/ – returns all physical contracts
- /Contracts/Physical/P10000.000 – does not exist
- /Contracts/Physical/ – does not exist
Don’t confuse POST and PUT
PUT=Update, POST=Create
- PUT /Contracts/Physicals?ConID=P10000.110 – updates this contract
- POST /Contracts/Physicals?ConID=P10000.110 – not allowed if contract exists
Response Types - It is common for REST services to allow multiple response types
e.g. application/xml or application/json
and the client to specify the preferred order of response types via the Accept header in the request. Requests without a response type will be rejected with a 406 Not Acceptable response, if the Accept header does not specifically contain one of the allowable types.
Protected HTTP Methods - RESTful API often use GET (read), POST (create), PUT (replace/update) and DELETE (to delete a record). However, not all of these are valid choices for every single resource collection, user, or action and invalid choices will be rejected (with a 403 Forbidden). Please check the ITAS Web Help site for the valid verbs for the web service you are interacting with.
Field Selection
Limit the attributes returned to just those needed to limit traffic and speed up api response times.
GET /cars?fields=manufacturer,model,id,color