¿Cómo hago que mis APIs sean usables? A través de un ejemplo desarrollado en Spring veremos como realizar todo el proceso de diseño aplicando un conjunto de buenas prácticas que te ayuden en el proceso de toma de decisión a la hora de enfrentarte al diseño de APIs.

1. Horneando APIs
Septiembre de 2018, v1.0

2. Índice
AUTORES Y CONTACTO

3. 1. ¿Por dónde empiezo?...conociendo los ingredientes

4. 1.- .¿Por dónde empiezo?
1
L
2
●
●
●

5. 1.- .¿Por dónde empiezo?
3
●
●
●

6. 1.1 Nomenclatura

7. ●
●●
1.1 - NOMENCLATURA
ANATOMÍA DE UNA URL
●
●
●
→

8. NOMBRE DE LOS RECURSOS
●
●
●
●
●
○
○
○
●
→
○
→
○
→
●
○
○
1.1 - NOMENCLATURA
●
→
●
→
●
● Terminar el nombre de los recursos con el carácter
“/”. Si se hace esto y tenemos por ejemplo:
/customers/{customer-id}/
/customers/{customer-id}/addresses
Al hacer una petición sobre el recurso .../addresses
se ejecutarán ambos.

9. PATH PARAMETERS
●
●
●
/customers/{customer-id}
/customers/{customer-id}/addresses/{address-id}
●
○
○
1.1 - NOMENCLATURA
●
→
●

10. QUERY PARAMETERS
●
●
●
●
●
1.1 - NOMENCLATURA
●
●
→
●
→

11. CAMPOS DE ENTRADA/SALIDA
●
●
○
○
○
●
○
○
○
{
...ATRIBUTOS DEL RECURSO…
}
{
“data”: {
...ATRIBUTOS DEL RECURSO...
},
“pagination”: {
...ATRIBUTOS DE LA PAGINACIÓN…
}
}
1.1 - NOMENCLATURA

12. CAMPOS DE ENTRADA/SALIDA
●
→
●
→
●
●
●
●
1.1 - NOMENCLATURA

13. CAMPOS DE ENTRADA/SALIDA
●
…
1.1 - NOMENCLATURA

14. 1.2 Tipos de recursos

15. ●
●
●
●
●
●
●
●
1..2- TIPOS DE RECURSOS

16. 2. ¿Cómo interaccionar con los métodos HTTP?

17. 2.1.- USO DE MÉTODOS HTTP
●
●
IDEMPOTENCIA Y MÉTODO SEGURO

18. ●
○
○
●
○
●
GET /customers/24535
●
200 OK
{ “data”: {
“id”:”24535”,
“name”:”Juan”,
“dni”: “4537567”
}
}
1
2.1.- USO DE MÉTODOS HTTP

19. ●
○
●
GET /customers
●
200 OK
{ “data”: [
{
“id”:”24535”,
“name”:”Juan”,
“dni”: “4537567”
},
{
“id”:”4567878”,
“name”:”Juan”,
“dni”: “546798”
}
]
}
1
2.1.- USO DE MÉTODOS HTTP

20. ●
○
○
●
●
POST /customers
{
“name”:”Juan”,
“dni”: “4537567”
}
●
201 Created
Location:/customers/24535
{ “data”: {
“id”:”24535”,
“name”:”Juan”,
“dni”: “4537567”
}
}
→
2
2.1.- USO DE MÉTODOS HTTP

21. ●
○
○
●
●
PUT /customers/4354
{
“name”:”Juan”,
“dni”: “4537567”
}
●
200 Ok /
204 No Content
{ “data”: {
“id”:”24535”,
“name”:”Juan”,
“dni”: “4537567”
}
}
3
2.1.- USO DE MÉTODOS HTTP
→

22. ●
○
○
●
○
■
→
■
→
■
→
→
→
■
4
2.1.- USO DE MÉTODOS HTTP

23. ●
●
PATCH /customers/4354
{
“name”:”Juan José”,
}
●
20O Ok /
204 No Content
{ “data”: {
“id”:”24535”,
“name”:”Juan José”,
“dni”: “4537567”
}
}
4
2.1.- USO DE MÉTODOS HTTP

24. ●
○
○
●
●
DELETE /customers/4354
●
204 No Content
5
2.1.- USO DE MÉTODOS HTTP

25. 2.2 ¿Cómo responder adecuadamente?

26. 2.2- ¿CÓMO RESPONDER ADECUADAMENTE?
1
Racksburg.
●
●
●
●
●
1
LOS CÓDIGOS HTTP

27. ●
●
●
●
●
1
Racksburg.
1
2.2- ¿CÓMO RESPONDER ADECUADAMENTE?
LOS CÓDIGOS HTTP

28. ●
●
●
●
●
1
Racksburg.
1
2.2- ¿CÓMO RESPONDER ADECUADAMENTE?
LOS CÓDIGOS HTTP

29. ●
●
●
●
●
1
Racksburg.
1
2.2- ¿CÓMO RESPONDER ADECUADAMENTE?
LOS CÓDIGOS HTTP

30. ●
●
●
●
●
1
Racksburg.
1
2.2- ¿CÓMO RESPONDER ADECUADAMENTE?
LOS CÓDIGOS HTTP

31. -
-
→
2.2- ¿CÓMO RESPONDER ADECUADAMENTE?
LOS CÓDIGOS HTTP

32. ●
●
●
○
●
●
●
FORMATO DE RESPUESTA COMÚN
{ “messages”:[
{
“type”:”ERROR”,
“alias”:”invalidParameter”,
“description”: “Los parámetros introducidos no son válidos”
}
]
}
2.2- ¿CÓMO RESPONDER ADECUADAMENTE?

33. 2.3 ¿Cómo versiono?

34. ●
Accept: Application/vnd.api.article+xml; version=1.0
●
X-API-Version: 1.0
●
api.example.com/ v1/resource
●
apiv1.example.com/resource
●
GET /something? version=1.0
TÉCNICAS DE VERSIONADO
2.3- ¿CÓMO VERSIONO?

35. V. 1. 3. 8
Fix bugs
Nueva
funcionalidad
Cambios
incompatibles
VERSIONADO EN LA DEFINICIÓN DE LA API
VERSIONADO EN LA URL DE INVOCACIÓN
Versionado semántico:
2.3- ¿CÓMO VERSIONO?

36. 2.4 ¿Cómo paginar?

37. ●
GET /items?limit=20
GET /items?limit=20&offset=20
GET /items?limit=20&offset=40
●
GET /items?limit=20
GET /items?limit=20&createBefore=2018-01-20T00:00:00
GET /items?limit=20&createBefore=2018-01-19T00:00:00
TÉCNICAS DE PAGINACIÓN
2.4- ¿CÓMO PAGINAR?
●
GET /items?limit=20
GET /items?limit=20&cursor=13740047775
GET /items?limit=20&cursor=13740047795

38. ●
●
GET /customers? pageSize=2
●
GET /customers? paginationKey=sd23246bhb
&pageSize=2
PROPUESTA DE PAGINACIÓN
2.4- ¿CÓMO PAGINAR?

39. {
"data": [
{
"id": "1234",
...
},
{
"id": "1235",
…
}
],
"pagination": {
"links": {
"self": "../customers/v0/customers?pageSize=2&paginationKey=2",
"first": "../customers/v0/customers?pageSize=2",
"last": "../customers/v0/customers?pageSize=2&paginationKey=6",
"previous": "../customers/v0/customers?pageSize=2&paginationKey=1",
"next": "../customers/v0/customers?pageSize=2&paginationKey=3"
}
}
}
PROPUESTA DE PAGINACIÓN
●
2.4- ¿CÓMO PAGINAR?

40. 2.5 ¿Cómo filtrar los resultados?

41. 2.5 - FILTRADO
GET /products?price[gte]=10&price[lte]=100
GET /products?price=gte:10&price=lte:100
GET /products?fromPrice=10&toPrice=100
●
●
●
?[campo][operador][valor]
FILTRADO BÁSICO
●

42. 2.5 - FILTRADO
FILTRADO BÁSICO

43. 2.6 ¿Cómo ordenar los resultados de un recurso?

44. 2.6.- ORDENACIÓN
●
GET /customers?sortBy=asc(email)
GET /customers?sortBy=desc(email)
GET /customers?sortBy=+email
GET /customers?sortBy=-email
GET /customers?sortBy=email.asc
GET /customers?sortBy=email.desc
GET /customers?sortBy=email&orderBy=asc
GET /customers?sortBy=email&ordery=desc
●
GET /customers?sortBy=+email
GET /customers?sortBy=-email
●
○
○
GET /users?sortBy=-lastName
GET /users?sortBy=+email
●
GET /users?sortBy=-lastName,+email
TÉCNICAS DE ORDENACIÓN

45. 3. Nuestra receta...la metodología del diseño de recursos

46. 3.-METODOLOGIA DE DISEÑO DE RECURSOS
1.- Entender la funcionalidad y
el flujo de la operativa
2.- Identificar las entidades
involucradas
3.- Tipificar los recursos o
entidades
4.- Relacionar los recursos
5.- Diseñar recursos y los
campos E/S
6.- Implementar la definición
de la API

47. 4. EJEMPLO

48. 1.- Entender la funcionalidad y
el flujo de la operativa
4.- EJEMPLO

49. 2.- Identificar las entidades
involucradas
/subscriptions
/profiles
/visualizations
/tv-shows
/films
/seasons /chapters
API Films
/recommendations
API
Subscriptions
API TV Shows
4.- EJEMPLO

50. 3.- Tipificar los recursos o
entidades
/subscriptions
/profiles
/visualizations
/tv-shows
/films
/seasons /chapters
API Films
/recommendations
Collection y document
Collection y document
Collection y document
Collection y document
Collection y documentCollection y document
Collection y document
Collection
API
Subscriptions
API TV Shows
4.- EJEMPLO

51. /subscriptions
/profiles
/visualizations
/tv-shows
/films
/seasons /chapters
API Films
/recommendations
Collection y document
Collection y document
Collection y document
Collection y document
Collection y documentCollection y document
Collection y document
Collection
4.- Relacionar los recursos 1:N
1:N
1:N 1:N
1:N
API
Subscriptions
API TV Shows
4.- EJEMPLO

52. 5.- Diseñar recursos y los
campos E/S
/subscriptions
/profiles
/visualizations
/tv-shows
/films
/seasons /chapters
API
Subscriptions API Films
/recommendations
Collection y document
Collection y document
Collection y document
Collection y document
Collection y documentCollection y document
Collection y document
Collection
1:N
1:N
1:N 1:N
1:N
API TV Shows
4.- EJEMPLO

53. /subscriptions
id
type
price
startDate
endDate
/profiles
/visualizations
/recommendations
/tv-shows
/films
/seasons /chapters
API Subscriptions API Films
1:N
1:N
1:N
1:N 1:N
POST /subscriptions
GET, PUT /subscriptions/{subscription-id}
API
TV Shows
4.- EJEMPLO

54. /subscriptions
id
type
price
startDate
endDate
/profiles
id
name
alias
avatar
/visualizations
/recommendations
/tv-shows
/films
/seasons /chapters
API Subscriptions API Films
1:N
1:N
1:N
1:N 1:N
POST /subscriptions
GET, PUT /subscriptions/{subscription-id}
GET, POST
/subscriptions/{subscription-id}/profiles
GET, PATCH
/subscriptions/{subscription-id}/profiles/
{profile-id}
API
TV Shows
4.- EJEMPLO

55. /subscriptions
id
type
price
startDate
endDate
/profiles
id
name
alias
avatar
/visualizations
id
visualizationContent
id
visualizationContentType
isFinished
startingPosition
/recommendations
/tv-shows
/films
/seasons /chapters
API Subscriptions API Films
1:N
1:N
1:N
1:N 1:N
POST /subscriptions
GET, PUT /subscriptions/{subscription-id}
GET, POST
/subscriptions/{subscription-id}/profiles
GET, PATCH
/subscriptions/{subscription-id}/profiles/
{profile-id}
POST
/subscriptions/{subscription-id/profiles/{profile-id}/visualizations
PATCH,GET
/subscriptions/{subscription-id/profiles/{profile-id}/visualizations
/{visualization-id}
API
TV Shows
4.- EJEMPLO

56. /subscriptions
id
type
price
startDate
endDate
/profiles
id
name
alias
avatar
/visualizations
id
visualizationContent
id
visualizationContentType
isFinished
startingPosition
/recommendations
visualizationContentType
percentageMatch
categories
/tv-shows
/films
/seasons /chapters
API Subscriptions API Films
1:N
1:N
1:N
1:N 1:N
POST /subscriptions
GET, PUT /subscriptions/{subscription-id}
GET, POST
/subscriptions/{subscription-id}/profiles
GET, PATCH
/subscriptions/{subscription-id}/profiles/
{profile-id}
POST
/subscriptions/{subscription-id/profiles/{profile-id}/visualizations
PATCH,GET
/subscriptions/{subscription-id/profiles/{profile-id}/visualizations
/{visualization-id}
GET
/subscriptions/{subscription-id}/profiles/
{profile-id}/recommendations
API
TV Shows
4.- EJEMPLO

57. /subscriptions
id
type
price
startDate
endDate
/profiles
id
name
alias
avatar
/visualizations
id
visualizationContent
id
visualizationContentType
isFinished
startingPosition
/recommendations
visualizationContentType
percentageMatch
categories
/tv-shows
id
name
shortDescription
longDescription
year
recommendedAge
categories
advertising
/films
/seasons /chapters
API Subscriptions API Films
1:N
1:N
1:N
1:N 1:N
POST /subscriptions
GET, PUT /subscriptions/{subscription-id}
4.- EJEMPLO
GET
/subscriptions/{subscription-id}/profiles/
{profile-id}/recommendations
GET, POST
/subscriptions/{subscription-id}/profiles
GET, PATCH
/subscriptions/{subscription-id}/profiles/
{profile-id}
POST
/subscriptions/{subscription-id/profiles/{profile-id}/visualizations
PATCH,GET
/subscriptions/{subscription-id/profiles/{profile-id}/visualizations
/{visualization-id}
GET /tv-shows?categories
GET /tv-shows/{tv-show-id}
API
TV Shows
4.- EJEMPLO

58. /subscriptions
id
type
price
startDate
endDate
/profiles
id
name
alias
avatar
/visualizations
id
visualizationContent
id
visualizationContentType
isFinished
startingPosition
/recommendations
visualizationContentType
percentageMatch
categories
/tv-shows
id
name
shortDescription
longDescription
year
recommendedAge
categories
advertising
/films
/seasons
id
name
/chapters
API Subscriptions API Films
1:N
1:N
1:N
1:N 1:N
POST /subscriptions
GET, PUT /subscriptions/{subscription-id}
GET
/subscriptions/{subscription-id}/profiles/
{profile-id}/recommendations
GET series/{series-id}/seasons
GET series/{series-id}/seasons/{season-id}
GET, POST
/subscriptions/{subscription-id}/profiles
GET, PATCH
/subscriptions/{subscription-id}/profiles/
{profile-id}
POST
/subscriptions/{subscription-id/profiles/{profile-id}/visualizations
PATCH,GET
/subscriptions/{subscription-id/profiles/{profile-id}/visualizations
/{visualization-id}
GET /tv-shows?categories
GET /tv-shows/{tv-show-id}
API
TV Shows
4.- EJEMPLO

59. /subscriptions
id
type
price
startDate
endDate
/profiles
id
name
alias
avatar
/visualizations
id
visualizationContent
id
visualizationContentType
isFinished
startingPosition
/recommendations
visualizationContentType
percentageMatch
categories
/tv-shows
id
name
shortDescription
longDescription
year
recommendedAge
categories
advertising
/films
/seasons
id
name
/chapters
id
name
duration
shortDescription
longDescription
API Subscriptions API Films
1:N
1:N
1:N
1:N 1:N
POST /subscriptions
GET, PUT /subscriptions/{subscription-id}
GET
/subscriptions/{subscription-id}/profiles/
{profile-id}/recommendations
GET, POST
/subscriptions/{subscription-id}/profiles
GET, PATCH
/subscriptions/{subscription-id}/profiles/
{profile-id}
POST
/subscriptions/{subscription-id/profiles/{profile-id}/visualizations
PATCH,GET
/subscriptions/{subscription-id/profiles/{profile-id}/visualizations
/{visualization-id}
GET series/{series-id}/seasons
GET series/{series-id}/seasons/{season-id}
GET /tv-shows?categories
GET /tv-shows/{tv-show-id}
API
TV Shows
GET series/{series-id}/seasons/{season-id}/chapters
GET series/{series-id}/seasons/{season-id}/chapters/ {chapter-id}
4.- EJEMPLO

60. /subscriptions
id
type
price
startDate
endDate
/profiles
id
name
alias
avatar
/visualizations
id
visualizationContent
id
visualizationContentType
isFinished
startingPosition
/recommendations
visualizationContentType
percentageMatch
categories
/tv-shows
id
name
shortDescription
longDescription
year
recommendedAge
categories
advertising
/films
id
name
shortDescription
longDescription
year
duration
recommendedAge
categories
/seasons
id
name
/chapters
id
name
duration
shortDescription
longDescription
API Subscriptions API Films
1:N
1:N
1:N
1:N 1:N
POST /subscriptions
GET, PUT /subscriptions/{subscription-id}
GET /films?categories
GET /films/{film-id}
GET series/{series-id}/seasons/{season-id}/chapters
GET series/{series-id}/seasons/{season-id}/chapters/ {chapter-id}
GET
/subscriptions/{subscription-id}/profiles/
{profile-id}/recommendations
GET, POST
/subscriptions/{subscription-id}/profiles
GET, PATCH
/subscriptions/{subscription-id}/profiles/
{profile-id}
POST
/subscriptions/{subscription-id/profiles/{profile-id}/visualizations
PATCH,GET
/subscriptions/{subscription-id/profiles/{profile-id}/visualizations
/{visualization-id}
GET series/{series-id}/seasons
GET series/{series-id}/seasons/{season-id}
GET /tv-shows?categories
GET /tv-shows/{tv-show-id}
API
TV Shows
4.- EJEMPLO

61. Editar el estilo de texto del patrón
Ejemplo práctico: Implementación con Spring

62. /subscriptions
/profiles
/visualizations
/recommendations
/tv-shows
/films
/seasons /chapters
API Subscriptions API Films
1:N
1:N
1:N
1:N 1:N
API
TV Shows
4.- EJEMPLO

63. /subscriptions
/profiles
/visualizations
/recommendations
/tv-shows
/films
/seasons /chapters
API Subscriptions API Films
1:N
1:N
1:N
1:N 1:N
API
TV Shows
4.- EJEMPLO

64. 4.- EJEMPLO
Subscriptions
Recommendations
Visualizations
Films
TV- Shows

65. 4.- EJEMPLO
Films
Visualizations
Subscriptions Recommendations TV- Shows

66. 4.- EJEMPLO
Subscriptions Recommendations
Visualizations
Films
TV- Shows

67. 4.- EJEMPLO
Subscriptions Recommendations
Visualizations
Films
TV- Shows

68. /subscriptions
id
type
price
startDate
endDate
/profiles
id
name
alias
avatar
/visualizations
id
visualizationContent
id
visualizationContentType
isFinished
startingPosition
/recommendations
visualizationContentType
percentageMatch
categories
/tv-shows
id
name
shortDescription
longDescription
year
recommendedAge
categories
advertising
/films
id
name
shortDescription
longDescription
year
duration
recommendedAge
categories
/seasons
id
name
/chapters
id
name
duration
shortDescription
longDescription
API Subscriptions API Films
1:N
1:N
1:N
1:N 1:N
POST /subscriptions
GET, PUT /subscriptions/{subscription-id}
GET /films?categories
GET /films/{film-id}
GET series/{series-id}/seasons/{season-id}/chapters
GET series/{series-id}/seasons/{season-id}/chapters/ {chapter-id}
GET
/subscriptions/{subscription-id}/profiles/
{profile-id}/recommendations
GET, POST
/subscriptions/{subscription-id}/profiles
GET, PATCH
/subscriptions/{subscription-id}/profiles/
{profile-id}
POST
/subscriptions/{subscription-id/profiles/{profile-id}/visualizati
ons
PATCH,GET
/subscriptions/{subscription-id/profiles/{profile-id}/visualizati
ons/{visualization-id}
GET series/{series-id}/seasons
GET series/{series-id}/seasons/{season-id}
GET /tv-shows?categories
GET /tv-shows/{tv-show-id}
API
TV Shows
4.- EJEMPLO

69. 4.- EJEMPLO
Subscriptions Recommendations
Visualizations
Films
TV- Shows
API GATEWAY