El método GET utiliza la ruta de la URL para determinar la colección o recurso que se desea obtener con, opcionalmente, parámetros adicionales que determinan el conjunto de resultados a obtener por la solicitud.
•Usa el verbo HTTP GET.
•No hay cuerpo de solicitud, es decir, la configuración no declara una cláusula “body”.
•El recurso o recursos mostrados están contenidos en el cuerpo de la respuesta.
•Cada recurso contenido en el cuerpo de la respuesta contiene los vínculos hipermedia (HATEOAS), lo que permite al consumidor de la API navegar dinámicamente a los recursos relacionados al mismo.
En todos los ejemplos se utiliza el formulario "Account (CRM_ACCOUNT)" de la aplicación CRM.
Ejemplo: Obtener todas las instancias del formulario "Account".
GET /forms/CRMACCOUNT/instances/
Parámetros Opcionales
En el caso que la solicitud devuelva una colección de recursos, la URL del método GET puede contener parámetros opcionales que permiten personalizar los resultados que se obtienen mediante dicha solicitud.
En cada solicitud pueden incluirse ninguno o varios de estos parámetros separados por el signo “&”. La sintaxis general es:
GET /collection-name?parameter=value[{¶meter=value}]
search
Mediante este parámetro podemos filtrar el contenido de la respuesta, utilizando notación RHS. Esta notación es de la forma:
fieldName=operator:value
Pueden incluirse dentro de este parámetro uno o varios filtros separados por “,”.
El valor de "fieldName" es el valor de la propiedad Identificador del recurso sobre el que se está realizando la solicitud.
Los valores posibles para "operator" son:
Valor |
Descripción |
|---|---|
eq |
Igual |
neq |
No igual |
like |
Contiene |
sw |
Comienza con |
nsw |
No comienza con |
ew |
Finaliza con |
new |
No finaliza con |
gt |
Mayor que |
gte |
Mayor igual que |
lt |
Menor que |
lte |
Menor igual que |
in |
Incluido en |
nin |
No incluido en |
Ejemplo 1: Buscar todas las instancias del formulario "Account" que tenga el valor “JPerez” en el campo correspondiente al vendedor.
GET /forms/CRM_ACCOUNT/instances?search=cdInstanceOwner=eq:JPerez
Ejemplo 2: Buscar todas las instancias del formulario "Account" que tenga el valor “JPerez” en el campo correspondiente al vendedor y el valor del campo correspondiente a la razón social que comience con el valor “Acme”.
GET /forms/CRM_ACCOUNT/instances?search=cdInstanceOwner=eq:JPerez,dsCompany=sw:Acme
sort
Este parámetro permite ordenar el contenido de la respuesta de acuerdo a las necesidades del consumidor de la API. La sintaxis es:
[+/-]fieldName
Pueden incluirse dentro de este parámetro uno o varios criterios de ordenamiento separados por “,”.
Los prefijos “+” o “-” indican si el ordenamiento es ascendente o si es descendente. Si se omite, se asume que el orden es ascendente.
Ejemplo 1: Obtener las instancias del formulario "Account" de manera ascendente por la cantidad de empleados de la cuenta.
GET /forms/CRM_ACCOUNT/instances?sort=qtEmployee
Ejemplo 2: Obtener las instancias del formulario "Account" de manera ascendente por la razón social de la compañía y dentro de ella, de manera descendente por la cantidad de empleados.
GET /forms/CRM_ACCOUNT/instances?sort=dsCompany,-qtEmployee
per-page
La respuesta a una solicitud es paginada. Significa que la API devuelve una página de los resultados obtenidos por la solicitud.
Mediante este parámetro se puede determinar el tamaño de estas páginas, es decir, la cantidad máxima de recursos que contiene la respuesta a la solicitud. La sintaxis es:
per-page=20
Este parámetro, como el resto, es opcional. En caso que se omita, la API toma en forma predeterminada este valor de la propiedad configurable Cantidad de líneas por página en la búsqueda de formularios.
Ejemplo: Definir el tamaño de la página con valor 20.
GET /forms/CRM_ACCOUNT/instances?per-page=20
page-number
En combinación con el parámetro per-page, este parámetro permite determinar qué subconjunto de los resultados correspondientes a una solicitud son incluidos en la respuesta. La sintaxis es:
page-number=3
Como también este parámetro es opcional, si el mismo se omite el valor predeterminado es 1.
Ejemplo 1: Devolver la página 2 con páginas de 10 recursos, es decir los recursos del 11 al 20.
GET /forms/CRM_ACCOUNT/instances?page-number=2
Ejemplo 2: Devolver la página 2 con páginas de 30 recursos, es decir los recursos del 31 al 60.
GET /forms/CRM_ACCOUNT/instances?per-page=30&page-number=2
Cada recurso contenido en la respuesta a una determinada solicitud incluye los vínculos hipermedia (Hypermedia as the Engine of Application State) que le permiten al consumidor de la API navegar dinámicamente a los recursos y métodos relacionados al recurso que se está accediendo.
En todos los casos, la respuesta para cada recurso incluye una lista del tipo:
•rel: Verbo HTTP que se debe invocar para acceder al recurso o método relacionado.
•label: Descripción del recurso o método relacionado.
•href: URL del recurso o método relacionado.
Ejemplo: Hacer una solicitud para obtener los datos de la instancia 91 del formulario "Account".
GET /forms/CRM_ACCOUNT/instances/91
La respuesta a esta solicitud incluye, además de las propiedades del formulario solicitado, la información para ejecutar los métodos de los recursos relacionados.
{ "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": "Partial Edit", "href": "http://miAmbiente/v1.0/forms/CRM_ACCOUNT/instances/91" }, { "rel": "DELETE", "label": "Remove", "href": "http://miAmbiente/v1.0/forms/CRM_ACCOUNT/instances/91" } ] }
|
Esta información permite dinámicamente:
•Realizar la edición de la instancia 91 del formulario
PUT /forms/CRM_ACCOUNT/instances/91
•Realizar la actualización de la instancia 91 del formulario
PATCH /forms/CRM_ACCOUNT/instances/91
•Realizar la eliminación de la instancia 91 del formulario
DELETE /forms/CRM_ACCOUNT/instances/91
