Ingens Blog

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

Subscribe to Email Updates

Lists by Topic

see all

Posts by Topic

See all

Recent Posts