Topics and tips in Web API design

Wander Lairson Costa

Software Engineer, Mozilla, Taskcluster Team

twitter

@walac

email

wcosta@mozilla.com

github

https://github.com/walac

Slides

https://walac.github.io/api-design-talk

{URI}/{RESOURCE/ENDPOINT}

• https://example.com/items
• https://example.com/items/10
• https://example.com/items/sorted
• https://example.com/items?sorted=true

• Idempotence
• HTTP verbs
• Errors code

A GET request is an idempotent operation to retrieve data from the resource.

A POST request adds new data to the resource.

PATCH verb requests data update on the resource. PATCH is idempotent.

PUT = PATCH || POST.

It does what it says: remove a data from the resource.

• Some requests require web server to response to a preflight (OPTION) request.
• Web server can control allowed domains, request and exposed headers.
• If your API needs a session key, make sure the web app stores it in a [local|session]Storage.
• Cors proxy

• Request parameters (except GET)
• Response
• Data validation
• Automated documentation
• Client bindings

• Dynamic vs static type
• Return codes vs exception handling
• Functional vs Procedural vs Object oriented

• Reference docs
• Tutorials
• Code samples
• Screencasts
• Mailing lists
• Open the source, Luke

• wcosta@mozilla.com
• @walac00
• https://github.com/walac
• Slides: https://walac.github.io/api-design-talk