Implementa el punto de acceso a todos los datos procesados y almacenados por datos.gob.mx en las distintas zonas disponibles mediante una interfaz HTTP(S) tipo REST.
Las rutas son estructuradas utilizando la colección de datos sobre la que se este trabajando de la siguiente forma:
API/API_VERSION/data.collection
Donde:
- API: Protocolo + IP/dominio + puerto donde el proceso front esta escuchando por peticiones
- API_VERSION: Versión del API que se desea usar
- data.collection: Colección de datos sobre la cual se esté trabajando
Un ejemplo de una ruta con todos sus componentes:
https://api.datos.gob.mx/v2/sinaica
Otras consideraciones importantes:
- Todas las operaciones devuelven JSON
- Todas las operaciones que esperan datos ( PUT y POST ) los esperan en JSON
- Todas las fechas seran devueltas en UTC y utilizando el formato ISO 8601
- Todas las operaciones esperan y devuelven datos en UTF8 mediante los encabezados adecuados: Content-Type: application/json; charset=utf-8
- Todas las operaciones deberán ser debidamente validadas. Para mas información consultar el apartado 'SEGURIDAD'; la única excepción serán las consultas ( operaciones GET ) a colecciones de datos marcadas como públicas
En el caso de operaciones de consumo la respuesta incluye el listado de resultados e información sobre la paginación.
{
"pagination": {
"page": 1,
"pageSize": 20,
"total": 133
},
"results": []
}
Todas las operaciones que se determinan en alguna condición de error regresan una estructura JSON que describe la condición y opcionalmente algunos detalles adicionales:
{
"error": "INVALID_DOCUMENT_ID",
"details": {}
}
- Existen 2 tipos principales de error; aquellos que se ocasionan del lado del cliente y aquellos que surgen del lado del servicio.
- La distinción entre ambos tipos de error se determinan por el encabezado HTTP de estatus devuelto por el servicio
- Los errores del lado del cliente devuelven un encabezado 4xx y deberán ser corregidos en la implementación del cliente.
- Los errores del lado del servicio devuelven un encabezado 5xx y deberán ser reportados como una incidencia a revisión.
Cuando una llamada se hace al API, este por defecto castea automaticamente los siguientes tipos de valores:
- Numero
- Expresión regular
- Fecha
- Booleano
- Texto vacio
Si deseas omitir este casteo automatico para poder hacer una igualdad con un número en formato string puedes usar una de las siguientes funciones:
- string(2890)
- date(2017-10-01)
/v2/(_data.collection_)?key1=string(10)&key2=date(2017-10-01)
Las consultas deberán ser realizadas contra el recurso de la colección de datos sobre la que se este trabajando y las condiciones ser expresadas como parte de la cadena de consulta Query String*.
Para expresar condiciones mas complejas que la igualdad absoluta, se pueden utilizar los siguientes operadores:
MongoDB | URI | Ejemplo | Resultado |
---|---|---|---|
$eq |
key=val |
type=public |
{filter: {type: 'public'}} |
$gt |
key>val |
count>5 |
{filter: {count: {$gt: 5}}} |
$gte |
key>=val |
rating>=9.5 |
{filter: {rating: {$gte: 9.5}}} |
$lt |
key<val |
createdAt<2016-01-01 |
{filter: {createdAt: {$lt: Fri Jan 01 2016 01:00:00 GMT+0100 (CET)}}} |
$lte |
key<=val |
score<=-5 |
{filter: {score: {$lte: -5}}} |
$ne |
key!=val |
status!=success |
{filter: {status: {$ne: 'success'}}} |
$in |
key=val1,val2 |
country=GB,US |
{filter: {country: {$in: ['GB', 'US']}}} |
$nin |
key!=val1,val2 |
lang!=fr,en |
{filter: {lang: {$nin: ['fr', 'en']}}} |
$exists |
key |
phone |
{filter: {phone: {$exists: true}}} |
$exists |
!key |
!email |
{filter: {email: {$exists: false}}} |
$regex |
key=/value/<opts> |
email=/@gmail\.com$/i |
{filter: {email: /@gmail.com$/i}} |
$regex |
key!=/value/<opts> |
phone!=/^06/ |
{filter: {phone: { $not: /^06/}}} |
/v2/(_data.collection_)?date-insert>2018-01-01&pagesize=50&sort=-date-insert
/v2/(_data.collection_)?parametro=PM10&estacionesid=300&date-insert>=2018-02-18&date-insert<=2018-02-19&pagezise=50
/v2/(_data.collection_)?filter={"$or":[{"key1":"value1"},{"key2":"value2"}]}
- Solo devolver id y url:
/v2/(_data.collection_)?fields=id,url
- Devolver todo menos id y url:
/v2/(_data.collection_)?fields=-id,-url
- pageSize: Indica el la cantidad de los registros devueltos. Por Default el número es
100
. - page: Indica el indice de los registros devueltos. Por Default el número es
1
.
- Útil para ordenar los registros devueltos
- La clave de operador predeterminada es
sort
- Acepta una lista de campos separados por comas
- El comportamiento predeterminado es clasificar en orden ascendentecual
- Use los prefijos
-
para ordenar en orden descendente
/v2/(_data.collection_)?sort=-points,createdAt
Se genera la adición de la colección “publishers” dentro de la colección “dataset”
-
Método:
GET
-
Ejemplos:
/api/dataset/join/publishers
/api/dataset/join/publishers?accrualPeriodicity=quincenal
-
Se pueden utilizar todos los filtrados, como se hace actualmente
-
Regresa:
{
"pagination": {
"pageSize": 100,
"page": 1,
"total": 1
},
"results": [
{ },
...
]
}
Se genera la adición de la colección “publishers” dentro de la colección “dataset”, obteniendo sólo un dataset
- Método:
GET
- Ejemplo:
/api/dataset/unique/un-titulo-aqui
- Regresa:
{
"response": "ok",
"results": [
{ }
]
}
Agrega un nuevo registro en la colección dataset
- Método:
POST
- Url:
/api/dataset
- Headers:
"Authorization": "<token>"
- Body: de acuerdo al esquema de
dataset
- Regresa:
{
"response": "ok",
"message": "Successful saved"
}
Agrega un nuevo registro en la colección dataset
- Método:
PUT
- Url:
/api/dataset?_id=<id de dataset a modificar>
- Headers:
"Authorization": "<token>"
- Body: de acuerdo al esquema de
dataset
- Regresa:
{
"response": "ok",
"message": "Successful saved"
}