There are three ways to provide parameters in request.
as part of URL
as query parameters
in body (payload)
Parameters as part of URL
One or several parameters can be provided as part of URL.
GET /organizations/:id/managers/:managerIdIn example there are provided two parameters.
Parameter
:idrefers to Organization ID.Parameter
:managerIdrefers to Manager ID.
As a response is returned the Manager by managerId in the Organization by :id (if both are found).
Parameters as query parameters
When using GET method, one or more query parameters can be appended to the URL. Parameters are added by using ?and separated with &. The parameter has always a key and a value.
The parameters can be used e.g. for filtering dataset or to support pagination.
GET /users?q=apinf&limit=10In example there are queried Users, who's document in database contains string
apinfin case such a documents are found, only first 10 documents are returned
As a convention in APInf the query condition parameter is named as q.
It depends on implementation, in which fields in database the actual filtering is performed. In APInf case as a response to the example query there are returned Users, who's document in database contains string apinf at least in one of the following fields:
username
company name
email address.
Pagination
In case the dataset, and expected response list, is large, the query parameters can be used in pagination. The APInf convention for naming pagination parameters is to use names skip and limit.
Parameter limit indicates the number of documents to return.
Parameter skip indicates the number of documents to skip before beginning to return list of documents.
In next example fifteen first found documents are skipped and then next five documents are returned as response.
GET /users?skip=15&limit=5
Date and Time formatting
either in Combined date and time in UTC format, e.g. 2012-07-14T01:00:00+01:00
or in Date format, e.g. 2012-07-14.
Payload in body
In case methods POST or PUT is used, the required payload is included in request body as type JSON. Because the parameters usually refer to fields in database, the APInf convention for parameter naming is to use camelCase in order to maintain consistency.
Documentation of request parameters
All parameters, their types and the way they are used must be described in generated documentation endpoint by endpoint.
Last updated