API REST 101:

Consejos y aclaraciones sobre REST API

¿Qué veremos?

• ¿Qué es una API?
• ¿Qué es REST API?
• ¿Cuándo usar REST API?
• Buenas prácticas
• Y... ¿GraphQL?

¿Qué es una API?

API != IPA

Application

Programing

Interface

Conjunto de subrutinas, funciones (o métodos) y procedimientos que ofrece una biblioteca para que otro software los utilice mediante una capa de abstracción

¿Qué es REST API?

Estilo de arquitectura de software para sistemas distribuidos que describe interfaces de comunicación mediante el protocolo HTTP

La base de comunicación de una API REST son las URL

¿Cuándo usar REST API?

Ahora si...

Buenas prácticas

(consejos a seguir)

Abstracto

vs

Concreto

Perros y Gatos, no Animales

Limones y Peras, no Frutas

CRUD como verbos HTTP

Operación CRUD

• Create
• Read
• Update
• Delete

Verbo HTTP

• POST
• GET
• PUT
• DELETE

Estructurar las URL

{protocol}://{domain}:[port]/{collection}/api/{version}/{resource}

http://localhost:8080/cinema/api/v1/movies
https://localhost:8080/cinema/api/v1/movies/1

IMPORTANTE

usar sustantivos y evitar verbos

(en lo posible)

HATEOAS

(wtf?!)

Hypermedia As The Engine Of Application State

{
    "movieId": 1,
    "name": "Avengers: Infinity War",
    "year": "2018",
    "links": [
        {
            "rel": "self",
            "url": "http://localhost:8080/cinema/api/v1/movies/1"
        },
        {
            "rel": "cast",
            "url": "http://localhost:8080/cinema/api/v1/movies/1/cast"
        }
    ]
}

Manejo de Errores

Ejemplo de un error en formato JSON

{
    "status": 204,
    "errorCode": 52,
    "errorMessage": "No existen películas en el sistema",
    "errorData": {
        "httpVerb": "PUT",
        "requestedUrl": "http://localhost:8080/cinema/api/v1/movies",
        "requestedParams": {}
    },
    "errorTimestamp": "2018-03-30 12:43:30"
}

Seguridad

Es MUY IMPORTANTE proteger las modificaciones de los recursos

Una táctica recomendada es solicitar headers de autenticación en los puntos que exponemos en nuestra API.

Idealmente estos headers debieran tener información encriptada de el usuario que está haciendo la solicitud, para poder filtrar por:

• Autenticación: ¿es un cliente válido en el sistema o es un externo no identificado?
• Autorización: ¿es un cliente con permisos suficientes para acceder al recurso solicitado?

Versionamiento

En software, SIEMPRE versionar todo tipo de API

Filtrado y Paginación

Filtrado

{
    "id": 42,
    "name": "Robert John Downey Jr.",
    "age": 52,
    "height": 1.72,
    "birthplace": "Manhattan, NY",
    "nationality": "USA",
    "movies": [...],
    "children": [...],
    "parents": [...]
}

{
    "id": 42,
    "name": "Robert John Downey Jr.",
    "age": 52
}

/actors/42

/actors/42?id,name,age

Paginación

[
    {"id": 1, ...},
    {"id": 2, ...},
    {"id": 3, ...},
    {"id": 4, ...},
    {"id": 5, ...},
    {"id": 6, ...},
    {"id": 7, ...},
    {"id": 8, ...},
    {"id": 9, ...},
    {"id": 10, ...},
    {"id": 11, ...},
    {"id": 12, ...},
    {"id": 13, ...},
    {"id": 14, ...},
    ...
]

/actors

/actors?limit=10&offset=30

[
    {"id": 31, ...},
    {"id": 32, ...},
    {"id": 33, ...},
    {"id": 34, ...},
    {"id": 35, ...},
    {"id": 36, ...},
    {"id": 37, ...},
    {"id": 38, ...},
    {"id": 39, ...},
    {"id": 40, ...}
]

Documentación

El principio de la documentación es aclarar lo que uno ha hecho a un tercero.

El principio de una API es hacer público lo que uno ha hecho, para que lo usen terceros.

apidocjs: http://apidocjs.com/example/

swagger: http://petstore.swagger.io

Y... ¿GraphQL?

Viene a reemplazar las REST API

Pero esto no ocurrirá hasta por lo menos unos años más. Es una tecnología emergente, mientras que REST API es el estándar usado en la industria actualmente

De todas formas, si saben GraphQL esto sumará valor a su curriculum

https://marmelab.com/blog/2017/09/08/dive-into-graphql-part-v-should-you-use-graphql.html

¡Gracias por su atención!