Requisitos de la API REST de Tractis
En esta página repasamos los requisitos que hay que tener en cuenta para integrarse con la API REST de Tractis.
Protocolo de comunicación
Al tratarse de una API REST todas las invocaciones de la API se realizan mediante HTTP. Las acciones de la API se invocan empleando dos datos: la operación HTTP (POST, GET, PUT o DELETE) y la URL.
Algunos ejemplos de acciones de la API de Tractis son:
- Crear contrato: POST /contracts
- Listar contratos: GET /contracts
- Listar templates: GET /templates
Debido a la naturaleza de los datos manejados en Tractis. Todas las invocaciones a la API han de realizarse mediante HTTPS de forma que la comunicación entre Tractis y el cliente vaya siempre cifrada.
Formato de comunicación
Tractis emplea las mismas URLs para servir la interfaz web HTML y para ofrecer la API XML. Es por esto que cuando invocamos una acción hemos de especificar siempre que estamos empleando la API y por tanto esperamos una respuesta XML.
Por tanto, para indicarle a Tractis que estamos invocando la API hemos de incluir siempre en las peticiones la cabecera HTTP Accept: application/xml
Además, cuando vayamos a pasarle a la API parámetros empleando un XML en el cuerpo de la petición hemos de hacérselo saber empleando la cabecera HTTP Content-Type: application/xml
Autenticación
Para utilizar la API de Tractis es necesario indicar el e-mail y la contraseña de la cuenta de usuario con la que se va a operar utilizando autenticación HTTP Básica.
Codificación de caracteres
Tractis trabaja con UTF-8 para facilitar el trabajo en distintos idiomas.
Códigos de estado
Tractis emplea los códigos de estado HTTP para dar información sobre el resultado de la acción invocada. Algunos de los códigos empleados por Tractis son:
- 200 OK: La petición se ha procesado correctamente.
- 201 Created: Se ha creado un recurso (por ejemplo, una petición post para crear un contrato).
- 401 Unauthorized: Las credenciales de autenticación son incorrectas.
Puedes consultar la lista completa de códigos de estado en el RFC2616 “Hypertext Transfer Protocol — HTTP/1.1″.
Ejemplo de invocación
A continuación se muestra un par de ejemplos de invocación de la API mediante el programa cURL:
$ curl -u demo@tractis.com:demouser \
-H 'Accept: application/xml' \
-i -X GET https://www.tractis.com/contracts
HTTP/1.1 200 OK
Status: 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<contracts total_items="1" pages="1" page="1" per_page="25">
<contract>
[...]
</contract>
</contracts>
$ curl -u demo@tractis.com:password \
-H 'Accept: application/xml' \
-H 'Content-Type: application/xml' \
-i -X POST https://www.tractis.com/contracts \
-d \
'<contract>
<name>Contrato de confidencialidad</name>
</contract>'
HTTP/1.1 201 Created
Status: 201 Created
Location: https://www.tractis.com/contracts/949981041
Content-Type: application/xml; charset=utf-8