API - Básicos necesarios para implementar una buena API REST

May 29, 2015 12:40:00 PM / by daniel.comas

 

 

Es bien conocido que la forma de desarrollo ha ido cambiando en los últimos años. Pasamos de los postbacks, sopas de tags, frameworks servidor a código cliente cosumiendo servicios REST.

 

Hoy os traemos un conjunto de buenas prácticas o básicos necesarios a la hora de hacer una buena API independientes del lenguaje que utilizéis.



Conceptos básicos


 

- Los tipos devueltos y enviados por JSON no han de ser string en el caso de que sean números o booleanos. En el caso de fechas un String (escoger un formato genérico, recomendable que incluya timezone) dado que no hay un estándar en la devolución de estas y así evitamos problemas con timespan de UNIX.

 

- Pasar datos generales que se usan en todas peticiones en los Headers (Custom headers, authorization, ...). Más fáciles de interceptar.

 

- Devolución de estructuras relacionadas

{
"id": 1,
"name": "trackname"
"event": {
"id": 1,
"name": "eventname"
}
}

 

- Con Arrays con muchos datos es recomendable que no se añadan en la misma estructura de datos. Es decir, se debería hacer otra petición con la relación y paginando.

/api/events/1

{
"id": 1,
"name": "eventname"
"No poner listado de tracks"
}

/api/events/1/tracks (nueva petición)

[
{
"id": 1,
"name": "trackname1"
"event": {
"id": 1,
"name": "eventname"
}
},
{
"id": 2,
"name": "trackname2"
"event": {
"id": 1,
"name": "eventname"
}
},
...
]

 

- En los listados GET añadir paginación y filtros de forma genérica

 

Request

GET /api/events?rows=25&page=1&sidx=name&sord=asc&filters=objeto

rows: rows per page

page: current page

sidx: field to order

sord: asc or desc

filters={"groupOp":"AND",

"rules":[

{"field":"id","op":"cn","data":"3034"},

{"field":"name","op":"cn","data":""}]}

 

Response

"page": 1, //current page

"rows": [{ //list of objects to return

"id": 3015,

"description": "asdasd",

...

}],

"total": 2, //total pages

"records": 36 //total registers

 

- Montar sistema de errores controlados con su correspondiente documento


- Sistema de autorización (ver post)

 

- CORS Activado (ver post)

 

Topics: API, Bearer Token, CORS, Ingens Developments, JavaScript, .NET, Oauth, PHP, Programación, Server

daniel.comas

Written by daniel.comas

Lists by Topic

see all
Servicios gestionados

Categorías

Ver todas