Tweet
Tweet

Slide 1

Slide 1 text

Practical Web APIs, rails’ style by Felipe Espinoza

Slide 2

Slide 2 text

fespinoza fespinozacast

Slide 3

Slide 3 text

No content

Slide 4

Slide 4 text

What is an API?

Slide 5

Slide 5 text

Application programming interface https://en.wikipedia.org/wiki/Application_programming_interface An API expresses a software component in terms of its operations, inputs, outputs, and underlying types. An API defines functionalities that are independent of their respective implementations, which allows definitions and implementations to vary without compromising the interface

Slide 6

Slide 6 text

My Definition Endpoint: a single IN/Out operation Web API: an API is a set of Endopints that establish a contract of the way Clients can communicate with the system exposing the API

Slide 7

Slide 7 text

Properties of good APIs consistent “self-documented” stable friendly regarding breaking changes interoperable secure useful :)

Slide 8

Slide 8 text

APIs in Rails HTTP 1.1 JSON Rails conventions REST* * Rails itself is not really restful, it lacks hateoas

Slide 9

Slide 9 text

Endpoint Structure

Slide 10

Slide 10 text

Request Response • HTTP verb • URL • Headers • Body/Parameters • Status Code • Headers • Body Endpoint Structure

Slide 11

Slide 11 text

No content

Slide 12

Slide 12 text

No content

Slide 13

Slide 13 text

No content

Slide 14

Slide 14 text

No content

Slide 15

Slide 15 text

https://gist.github.com/fespinoza/440b250d19a0e9979909

Slide 16

Slide 16 text

Basic Concerns About Endpoints

Slide 17

Slide 17 text

Authentication • HTTP Auth: when i don’t need to know who is logging in • Token Based Auth: when i want to identify the user and authenticate him • Authorization header • JWT tokens FTW! http://jwt.io Secure

Slide 18

Slide 18 text

Error normalization { "error": { "status": 422, "id": "unprocessable_entity", "message": "The given params are not valid", "documentation_url": "https://api.com/docs", "validations": { "title": [ "can't be blank" ] } } } Consistent

Slide 19

Slide 19 text

Endpoint design 1. Create a proposal in markdown 2. Make a PR out of it 3. Discuss and finally agree 4. Mock it! 5. Profit Useful :)

Slide 20

Slide 20 text

1. Create a proposal in markdown Useful :)

Slide 21

Slide 21 text

2. Discussions 2. Make a PR out of it Useful :)

Slide 22

Slide 22 text

3. Agree 3. Discuss and finally agree Useful :)

Slide 23

Slide 23 text

4. Mock it 4. Mock it! Useful :)

Slide 24

Slide 24 text

5. Profit! Useful :)

Slide 25

Slide 25 text

Useful HTTP headers Request Response ◦ Content-Type ◦ Accept ◦ Accept-Language ◦ Authorization ◦ If-None-Match ◦ User-Agent ◦ ETag ◦ Content-Type Interoperable

Slide 26

Slide 26 text

HTTP status codes

Slide 27

Slide 27 text

Interoperable

Slide 28

Slide 28 text

HTTP status codes Range Meaning 2XX Success 3XX Redirection 4XX Client error 5XX Server error Interoperable

Slide 29

Slide 29 text

Design Guidelines https://github.com/interagent/http-api-design https://github.com/hyperoslo/api-playbook Consistent

Slide 30

Slide 30 text

Oops* *let’s avoid the extra O with proper ops • logging • error tracking • uptime checking • performance monitoring • event tracking => Papertrail => Sentry/App Signal => Nagios => New relic, App Signal, Skylight => Mix pannel Stable

Slide 31

Slide 31 text

Rails Gems

Slide 32

Slide 32 text

Authentication gem 'devise' gem 'doorkeeper' gem 'doorkeeper-jwt' gem 'cancancan' https://github.com/doorkeeper-gem/doorkeeper https://github.com/chriswarren/doorkeeper-jwt Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwib… Secure

Slide 33

Slide 33 text

Versioning gem 'api-versions' • version: • routes • controllers • views • a new version of the enpoint, defaults to the previous version Accept: application/json, application/vnd.myshop+json; version=2 Change Friendly https://github.com/EDMC/api-versions

Slide 34

Slide 34 text

Testing & Documentation gem 'rspec_api_documentation' gem 'apitome' https://github.com/zipmark/rspec_api_documentation https://github.com/modeset/apitome https://github.com/Apipie/apipie-rails self-documented • Other Alternative

Slide 35

Slide 35 text

No content

Slide 36

Slide 36 text

No content

Slide 37

Slide 37 text

Paw https://luckymarmot.com/paw

Slide 38

Slide 38 text

https://speakerdeck.com/fespinoza/practical-web-apis-rails-style

Slide 39

Slide 39 text

Thanks! fespinoza fespinozacast