Cómo construir un API del que tus padres se sientan orgullosos

Necesitas construir una API, ¿pero conoces qué herramientas deberías usar? Cada día aparecen nuevas herramientas pensadas para crear, testear y desplegar APIs. En esta charla se presentará de manera resumida un caso real: el proceso de construcción de una API usando Python desde su diseño hasta su puesta en producción. Veremos los problemas encontrados por nuestro equipo y obviamente sus soluciones.

Transcript

1. Cómo construir un API del que tus padres se sientan orgullosos
2. About Me GET /speakers/adrian-matellanes { "name": "Adrián Matellanes", "roles": [ "Lead API Developer", "Málaga Python Organizer" ], "worksAt": "Ebury" "twitter": "@_amatellanes", "github": "github.com/amatellanes" }
3. We’re building an API !
4. We’re building a RESTful API !
5. What is a RESTful API ?
6. What is a RESTful API? Constraints • Client-Server • Stateless • Cacheable • Layered System • Uniform Interface
7. What is a RESTful API? Uniform Interface • Identification of resources • Manipulation of resources through representations • Self Descriptive Messages • Hypermedia As The Engine Of Application State (HATEOAS)
8. RMM Richardson Maturity Model http://martinfowler.com/articles/richardsonMaturityModel.html
9. RMM (Richardson Maturity Model) Level 1: Resources • GET - /api/characters • GET - /api/characters/583 • GET - /api/characters/211
10. RMM (Richardson Maturity Model) Level 2: HTTP Verbs • GET • POST • DELETE • PUT • PATCH • OPTIONS • HEAD
11. RMM (Richardson Maturity Model) Level 2: HTTP Verbs • POST - /api/characters • GET - /api/characters • GET|PUT|DELETE - /api/characters/823
12. RMM (Richardson Maturity Model) Level 3: Hypermedia controls GET /api/houses/362 { "name": "House Stark of Winterfell", "region": "The North", "words": "Winter is Coming", "founder": "/api/characters/209", }
13. RMM (Richardson Maturity Model) Level 3: Hypermedia controls HAL http://stateless.co/hal_specification.html JSON-LD http://json-ld.org/ Collection+JSON http://amundsen.com/media-types/collection/ JSON Schema http://json-schema.org/
14. HTTP Status Code
15. HTTP Status Code 2xx Success • 200 - OK • 201 - Created • 204 - No Content
16. HTTP Status Code 3xx Redirection • 301 - Moved Permanently • 304 - Not Modified
17. HTTP Status Code 4xx Client Error • 400 - Bad Request • 401 - Unauthorized • 403 - Forbidden • 404 - Not Found • 405 - Method Not Allowed
18. HTTP Status Code 5xx Server Error • 500 - Internal Server Error • 501 - Not Implemented • 502 - Bad Gateway • 503 - Service Unavailable
19. How to build a RESTful API?
20. API
21. Specification Development Testing Deployment
22. Specification Testing Deployment Development
23. Specification Deployment Development Testing
24. Specification Development Testing Deployment
25. API Specification
26. API Specification Swagger 6,316 results 3,870 repositories 4,664 stars 528,000 results http://swagger.io/specification/
27. API Specification Swagger swagger: '2.0' info: version: '1.0.0' title: Game of Thrones API Description: All the data from the universe of Ice And Fire you've ever wanted schemes: - https basePath: /v1 produces: - application/json securityDefinitions: OauthSecurity: type: oauth2 flow: accessCode authorizationUrl: 'https://oauth.simple.api/authorization' tokenUrl: 'https://oauth.simple.api/token' ...
28. API Specification Swagger … paths: /characters/{id}: get: summary: Get specific character parameters: - name: id in: path description: The identifier of this character required: true type: string responses: 200: description: History information for the given character schema: $ref: '#/definitions/Character' ...
29. API Specification Swagger … definitions: Character: type: object properties: name: type: string description: The name of this character gender: type: string description: The gender of this character example: name: Oberyn Martell gender: Male
30. API Specification RAML 506 results 834 repositories 2,329 stars 98,000 results https://github.com/raml-org/raml-spec
31. API Specification RAML #%RAML 1.0 title: Game of Thrones API version: v1 baseUri: http://{hostName}.com baseUriParameters: hostName: description: The name of the host mediaType: application/json documentation: - title: Game of Thrones API Documentation content: All the data from the universe of Ice And Fire you've ever wanted securitySchemes: oauth_2_0: !include securitySchemes/oauth_2_0.raml ...
32. API Specification RAML … /characters: /{id}: uriParameters: id: type: number description: The identifier of this character get: description: | Get specific character responses: 200: body: application/json: schema: !include schemas/character.json example: !include examples/character.json
33. API Specification RAML # schemas/character.json { "type": "object", "$schema": "http://json-schema.org/draft-03/schema", "required": true, "properties": { "name": { "type": "string", "required": true, "maxLength": 125 }, "gender": { "type": "string" } } }
34. API Specification RAML # examples/character.json { "name": "Oberyn Martell" "gender": "Male" }
35. API Specification API Blueprint 943 results 409 repositories 4,325 stars 404,000 results https://github.com/apiaryio/api-blueprint
36. API Specification API Blueprint FORMAT: 1A HOST: http://got.api.com/ # Game of Thrones API All the data from the universe of Ice And Fire you've ever wanted. ...
37. API Specification API Blueprint ... # Group Characters ## Character Resource [/characters/{id}] + Parameters + id: 422 (number) - The identifier of this character ### Get specific character [GET] + Response 200 (application/json) + Attributes - characters (Character) ...
38. API Specification API Blueprint ... # Data Structures ## Character (object) - name: Oberyn Martell (required, string) - The name of this character - gender: Male (required, string) - The gender of this character
39. What should I choose?
40. API Specification The API Transformer: Convertron https://apimatic.io/transformer
41. API Specification API Documentation Generator https://github.com/lord/slate
42. API Specification API Documentation Generator https://apiary.io/
43. API Development
44. What framework should I choose?
45. API Development What I DO want • Python 3 Support • HTTP request/response • Easy to understand and use (documentation, minimal magic, no surprise) • Packages • URL Routing (RESTful) • WSGI
46. API Development What I DO NOT want • Object-Relational Manager (no DB connection) • Template engine
47. API Development The Contenders
48. Flask
49. API Development Awesome Python webargs - Parse HTTP request arguments https://github.com/sloria/webargs marshmallow - Simplified object serialization https://github.com/marshmallow-code/marshmallow Requests - HTTP for Humans https://github.com/kennethreitz/requests
50. API Development Awesome Flask Flask-RESTful - Quick building REST APIs https://github.com/flask-restful/flask-restful Flask API - Browsable Web API https://github.com/tomchristie/flask-api Connexion - Automagically handles HTTP requests based on Swagger Spec https://github.com/zalando/connexion
51. API Development Flask-RESTful Example from flask import Flask from flask_restful import Resource, Api app = Flask(__name__) api = Api(app) ...
52. API Development Flask-RESTful Example ... class Character(Resource): def get(self, id): return { 'name': 'Oberyn Martell', 'culture': 'Dornish' } api.add_resource(Character, '/characters/<string:id>') ...
53. API Development Flask-RESTful Example ... if __name__ == '__main__': app.run(debug=True)
54. API Testing
55. API Testing Unit Testing unittest https://docs.python.org/3/library/unittest.html pytest https://github.com/pytest-dev/pytest nose https://github.com/nose-devs/nose
56. API Testing Mocking Requests HTTPretty https://github.com/gabrielfalcao/HTTPretty httmock https://github.com/patrys/httmock mock https://docs.python.org/3/library/unittest.mock.html
57. API Testing HTTPretty Example @httpretty.activate def test_got_api_returning_deals(): httpretty.register_uri(httpretty.GET, 'http://api.got.com/v1/characters/583', body='{'name': 'Jon Snow'}', content_type='application/json') response = requests.get('http://api.got.com/v1/characters/583') expect(response.json()).to.equal({'name': 'Jon Snow'})
58. Integration Testing Postman
59. Integration Testing Dredd A language-agnostic command-line tool for validating API description document against backend implementation of the API. https://github.com/apiaryio/dredd
60. Integration Testing Wiremock Mock your APIs for fast, robust and comprehensive testing https://github.com/tomakehurst/wiremock
61. Integration Testing Wiremock stub example { "request": { "method": "GET", "url": "/v1/characters/583" }, "response": { "status": 200, "bodyFileName": "jon-snow.json", "headers": { "Content-Type": "application/json" } } }
62. CDC Consumer Driven Contracts http://martinfowler.com/articles/consumerDrivenContracts.html
63. API Testing Performance Testing ab https://httpd.apache.org/docs/2.4/programs/ab.html Locust https://github.com/locustio/locust wrk https://github.com/wg/wrk
64. API Testing Security Testing Secure Pro https://smartbear.com/product/ready-api/secure/overview/
65. API Deployment
66. API Deployment API Gateway http://microservices.io/patterns/apigateway.html
67. API Deployment API Gateway Amazon API Gateway https://aws.amazon.com/api-gateway/ Kong https://getkong.org/
68. API Deployment Serverless
69. API Developer Portal
70. Your API is not for machine, is for people
71. API Developer Portal Tips • Document precisely and with examples • Authentication • Endpoints • SDKs • Changelog
72. More...
73. More... API Design Guides PayPal API Style Guide https://github.com/paypal/api-standards Heroku Platform HTTP API Design Guide https://github.com/interagent/http-api-design Microsoft REST API Guidelines https://github.com/Microsoft/api-guidelines
74. More... API Examples GitHub API v3 https://developer.github.com/v3/ Facebook Graph API https://developers.facebook.com/docs/graph-api Twitter REST API https://dev.twitter.com/rest/public Spotify Web API https://developer.spotify.com/web-api/
75. What’s missing....?
76. What’s missing....? :( • Versioning • Authentication • GraphQL
77. Thank you! Questions?