The GET method uses the URL path to determine the collection or resource to get with, optionally, additional parameters that determine the set of results to get for the request.
•It uses the HTTP GET verb.
•There is no request body, that is, the configuration does not declare a "body" clause.
•The displayed resource or resources are contained in the response body.
•Each resource contained in the response body contains hypermedia links (HATEOAS), which allows the API consumer to dynamically navigate to related resources.
In all the examples the "Account (CRM_ACCOUNT)" form of the CRM application is used.
Example: Get all "Account" form instances.
GET /forms/CRM_ACCOUNT/instances/
Optional Parameters
If the request returns a collection of resources, the GET method URL may contain optional parameters that allow customizing the results obtained by that request.
None or several of these parameters may be included in each request, separated by the “&” sign. The general syntax is:
GET /collection-name?parameter=value[{¶meter=value}]
search
Through this parameter, the response content can be filtered using RHS notation. This notation is:
fieldName=operator:value
One or several filters separated by “,” may be included within this parameter.
The "fieldName" value is that of the Identifier property of the resource on which the request is being made.
The possible values for "operator" are:
Value |
Description |
|---|---|
eq |
Equal |
neq |
Not equal |
like |
Contains |
sw |
Starts with |
nsw |
Does not start with |
ew |
Ends with |
new |
Does not end with |
gt |
Greater than |
gte |
Greater than equal to |
lt |
Less than |
lte |
Less than equal to |
in |
Included in |
nin |
Not included in |
Example 1: Search all "Account" form instances that have "JPerez" value in the field corresponding to the seller.
GET /forms/CRM_ACCOUNT/instances?search=cdInstanceOwner=eq:JPerez
Example 2: Search all "Account" form instances that have "JPerez" value in the field corresponding to the seller and the value of the field corresponding to the company name that starts with the “Acme” value.
GET /forms/CRM_ACCOUNT/instances?search=cdInstanceOwner=eq:JPerez,dsCompany=sw:Acme
sort
This parameter allows sorting the response content according to the needs of the API consumer. The syntax is:
[+/-]fieldName
One or several sorting criteria separated by “,” may be included within this parameter.
Prefixes "+" or "-" indicate whether it is an ascending or descending sorting. If omitted, the sorting is assumed to be ascending.
Example 1: Get the"Account" form instances in ascending sorting by the number of employees in the account.
GET /forms/CRM_ACCOUNT/instances?sort=qtEmployee
Example 2: Get the "Account" form instances in ascending sorting by the company name and within it, in descending sorting by the number of employees in the account.
GET /forms/CRM_ACCOUNT/instances?sort=dsCompany,-qtEmployee
per-page
The response to a request is paginated. It means that the API returns a page of the results obtained by the request.
The size of these pages can be determined using this parameter, that is, the maximum amount of resources that the request response contains. The syntax is:
per-page=20
This parameter, like the rest of them, is optional. If omitted, the API takes the following configurable property value Number of lines per page when searching for forms.
Example: Define the page size with value 20.
GET /forms/CRM_ACCOUNT/instances?per-page=20
page-number
In combination with the per-page parameter, this parameter allows to determine the subset of results corresponding to a request that are included in the response. The syntax is:
page-number=3
As this parameter is also optional, if omitted, the default value is 1.
Example 1: Return page 2 with pages having 10 resources, that is, resources from 11 to 20.
GET /forms/CRM_ACCOUNT/instances?page-number=2
Example 2: Return page 2 with pages having 30 resources, that is, resources from 31 to 60.
GET /forms/CRM_ACCOUNT/instances?per-page=30&page-number=2
Each resource contained in the response to a given request includes hypermedia links (Hypermedia as the Engine of Application State) that allow the API consumer to dynamically navigate to resources and methods related to the resource being accessed.
In all cases, the response for each resource includes a list of the type:
•rel: HTTP verb to be invoked to access the related resource or method.
•label: Description of the related resource or method.
•href: URL of the related resource or method.
Example: Make a request to get data from instance 91 of the "Account" form.
GET /forms/CRM_ACCOUNT/instances/91
The response to this request includes, in addition to properties of the requested form, the information to execute the methods of related resources.
{ "idForm": 91, "cdStatus": "2", "phone": null, "cdUserLastUpdate": "GDIAZ", "dtLastUpdate": "1605867184000", "email": null, "dsIndustry": "13", "cdUserStore": "GDIAZ", "dtStore": "1587510800000", "dsOwner": "Diaz, Guillermo", "dtOpening": "1587610000000", "dsHolding": "ACME", "links":[ { "rel": "PUT", "label": "Edit", "href": "http://miAmbiente/v1.0/forms/CRM_ACCOUNT/instances/91" }, { "rel": "PATCH", "label": "PartialEdit", "href": "http://miAmbiente/v1.0/forms/CRM_ACCOUNT/instances/91" }, { "rel": "DELETE", "label": "Remove", "href": "http://miAmbiente/v1.0/forms/CRM_ACCOUNT/instances/91" } ] }
|
This information dynamically allows:
•Editing instance 91 of the form
PUT /forms/CRM_ACCOUNT/instances/91
•Updating instance 91 of the form
PATCH /forms/CRM_ACCOUNT/instances/91
•Deleting instance 91 of the form
DELETE /forms/CRM_ACCOUNT/instances/91
