Good, Bad, Api

I don't know, how to create a good REST API. I know, how to create a bad one though.

Transcript

1. Frontend Frontier How to successfully create a good web API
2. –Vyacheslav Bikbaev, proud frontend developer “What is a good web API? I wish I knew.”
3. (well, at least) 6 Deadly sins How to successfully create a terrible web API , so everyone will love you feat.
4. 0. Designing Good Ignore planning, start implementing. You can’t design everything. Don’t discuss it with frontend devs/rest of your team: they love surprises. Bad • Gather requirements • Use some standard: json:api/OData/Swagger/etc. • Share results in your team, discuss.
5. 1. Documentation Good • Don’t have any OR • Never update it (bonus points if your project is public) Bad • Don’t have any but have readable schema/etc. OR • Have up-to-date documentation (bonus points if it is generated from actual code)
6. II. Consistency Good { "名前": "John", "фамилия": "Doe", "registerDay": "21/01/2012", "last_active_Date": "1518043779" } (bonus points for secretly changing fields at Friday evening AND/OR right before the deadline) Bad { "first_name": "John", "last_name": "Doe", "registration_date": "1327104000", "last_active_date": "1518043779" }
7. 3. RESTfull-ness Good GET: /getAllCompanies GET: /getCompany POST: /addCompany GET: /deleteCompany POST: /updateCompany Bad GET: /companies GET: /companies/1 POST: /companies DELETE: /companies/1 PATCH: /companies/1
8. 4. Breaking changes Good /api/blogposts/id1 /articles/1 Bad /api/v1/blogposts/id1 /api/v2/articles/1 (bonus points if your project is public and you don’t tell anyone about changes)
9. 5. Response status codes GOD TIER Boring tier • Meaningful status codes • Error codes for machine • Error message for humans • json:api errors
10. How to be less evil? Overall: REST misconceptions explained (must read) https://philsturgeon.uk/api/2017/12/18/rest-confusion-explained/ 2, 3, 4: Best(?) practices https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design https://hackernoon.com/restful-api-designing-guidelines-the-best-practices-60e1d954e7c9 https://www.toptal.com/api-developers/5-golden-rules-for-designing-a-great-web-api 5: Status codes https://philsturgeon.uk/http/2015/09/23/http-status-codes-are-not-enough/ http://jsonapi.org/format/#errors https://developer.twitter.com/en/docs/basics/response-codes 0: Designing https://swagger.io/ http://jsonapi.org/ http://www.odata.org/
11. Thank you. telegram: @la_sintez mail: viacheslav@soramitsu.co.jp Vyacheslav Bikbaev, creating sharp web at Soramitsu