This document discusses designing a JSON/REST API for a mobile app. It covers key choices like using REST vs GraphQL vs SOAP, having an open vs private API, and security considerations. It also discusses how to avoid breaking changes by following standards like JSON API, choosing the right data granularity, and using versioning. The document provides tips on forcing app updates, configuring behaviors, and communicating through documentation.

1. Designing a JSON / REST API
for your mobile app

2. Agenda
● Key choices
○ REST vs GraphQL vs SOAP
○ Open vs Private
○ Security
● How to stay flexible and avoid breaking changes
○ Request and response format advices
○ Choosing the right granularity
○ Versioning
● Tips and tricks
○ Forcing an app update
○ Configuring key behaviors
○ Communicating efficiently with documentation

3. Key choices

4. Key choices : SOAP vs REST vs GraphQL

5. Key choices : SOAP vs REST vs GraphQL
REST :
● "Traditionnal” approach
● Exposes business ressources
● Well known and documented
● Everybody already knows it in your team
● Performance bottleneck are predictible

6. Key choices : SOAP vs REST vs GraphQL
GraphQL :
● New kid on the block
● Developped by Facebook
● Single endpoint
● Client teams are autonomous to compose and fetch data
● Faster UI iterations
● Server side libraries are young
● Already used in production at big names (Github)

7. Key choices : Open vs Private
Things to take into consideration :
● Volumetry is harder to predict
● Security (rate limiting, etc)

8. Key choices : Security
Authent :
● OAUTH
● Custom ‘single’ token
● JSON Web Token
○ Signed payload
○ User id + metadata

9. How to stay flexible and avoid breaking
changes

10. Request and response format advices
● Use JSON API standard as much as possible : http://jsonapi.org/
● Always use a root element
● Always prefer hash

11. Choosing the right granularity
You win when you can iterate over your UI without changing your API (think
open API, GraphQL) :
● Do not expose your DB schema over HTTP
● Avoid 1 screen = 1 call
● Think in terms of macro component

12. Versionning
● Always start with a V0
● Avoid as much as possible breaking changes
● Keep your API consistent (you will iterate when you start a new product)

13. Tips and tricks

14. Forcing an app update
● Use API keys
● Return a custom error code
● Display webview

15. Configuring key behaviors
● For native client : Use a config endpoint (especially param that impact
volumetry , ex : polling, high uncertainty)

16. Communicating efficiently with
documentation
● Documentation as a conception tool
● Documentation get updating when it lives in the source code (annotations)
● Swagger, apiary

17. Annexes

18. References
http://jsonapi.org/
http://blog.octo.com/strategie-d-architecture-api/
http://blog.octo.com/designer-une-api-rest/
https://people.mpi-inf.mpg.de/~jblanche/api-design.pdf
https://github.com/interagent/http-api-design
https://speakerdeck.com/ijansch/scenario-driven-api-design-apidays-paris