APIDays 2018 - API Development Lifecycle - The secret ingredient behind RESTful APIs Specifications
•
1 like•264 views
Talk by Julie Rollin, Product Manager, and Hugo Hache, Lead Back-End Developer at FABERNOVEL TECHNOLOGIES
Recommended
More Related Content
Similar to APIDays 2018 - API Development Lifecycle - The secret ingredient behind RESTful APIs Specifications
Similar to APIDays 2018 - API Development Lifecycle - The secret ingredient behind RESTful APIs Specifications (20)
Recently uploaded
Recently uploaded (20)
APIDays 2018 - API Development Lifecycle - The secret ingredient behind RESTful APIs Specifications
- 1. THE SECRET INGREDIENT BEHIND RESTful APIs SPECIFICATIONS How to better document, make relevant examples and better test APIs ? Paris, 30th of january 2018
- 2. 2// Who has already met a crash on frontend due to a response not matching the API specification?
- 3. 3// Who has already heard about JSON schema concept?
- 4. 4// 01 // The problems we faced
- 5. 5// Design UX/UI IS legacy opening and integraton Architecture Devops Front end web Big Data, Smart Data, Fast Data Back end web AI (chat bots, machine learning…) SaaS - PaaS / Cloud IOT Mobile Apps (development, product management) API management Front end web
- 6. 6// Customers, Project Managers, Developers There is a crash on my app!!! Customer detects a problem on her app...
- 7. 7// Customers, Project Managers, Developers Project Manager tries to find where the problem comes from... There is a crash on my app!!! We’re looking for the source of the problem
- 8. 8// Customers, Project Managers, Developers Regarding logs, Project Manager has identified it’s related to a specific API call There is a crash on my app!!! We’re looking for the source of the problem Where does it come from? Let’s have a look at the logs Oh it seems to be related to this specific API call
- 9. 9// Customers, Project Managers, Developers Project Manager asks the developer why we have met this problem and how to fix it... Could you fix it quickly please? It’s critical... Could you tell me why the app crash when it does such API call please?
- 10. 10// Customers, Project Managers, Developers Developer gives the diagnosis... Could you tell me why the app crash when it does such API call please? Oh I see why it’s crashing... Could you fix it quickly please? It’s critical...
- 11. 11// Customers, Project Managers, Developers Developer gives the diagnosis...API specification does not match the current response that causes the frontend crash! Could you tell me why the app crash when it does such API call please? Oh I see why it’s crashing... ..it’s because API specification I used for my dev does not match this response... Could you fix it quickly please? It’s critical...
- 12. 12// Customers, Project Managers, Developers We wonder where is the truth… we all faced the same problems WHICH SPECIFICATIONS ARE WE TALKING ABOUT? WHICH SPECIFICATIONS ARE WE TALKING ABOUT? WHICH SPECIFICATIONS ARE WE TALKING ABOUT?
- 13. 13// Yesterday: different tools to test, document and mock APIs Test tool spec (e.g. POSTMan)
- 14. 14// Yesterday: different tools to test, document and mock APIs Documentation tool spec (e.g. Word, Swagger) Test tool spec (e.g. POSTMan)
- 15. 15// Yesterday: different tools to test, document and mock APIs Documentation tool spec (e.g. Word, Swagger) Mocking tool spec (e.g. WireMock) Test tool spec (e.g. POSTMan)
- 16. 16// Finding a way to have a single source of truth! The goal?
- 17. 17// Three options One tool to rule them all (POSTMan, Restlet have more & more features) Synchronize different tools, highly dependent on what they allow to import or export Build a new tool 01 02 03
- 18. 18// 02 // How to specify a JSON?
- 19. 19// JSON Schema { "title": "Person", "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "age": { "description": "Age in years", "type": "integer", "minimum": 0 } }, "required": ["firstName", "lastName"] } Example
- 20. 20// JSON Schema What does it allow you to do? Test Documentation Mock
- 21. 21// 03 // How to expand JSON schema concept to RESTful API level?
- 22. 22// Resource Example - A user User
- 23. 23// Attributes of a resource Example - A user id firstname lastname age User { "user": { "id": 1200, "firstname": "Arthur", "lastname": "Martin", "age": 17 } } JSON Instance
- 24. 24// Get user information GET /users/:id Routes Example - user resource Create a user POST /users Update a user PUT /users/:id Delete a user DELETE /users/:id
- 25. 25// Pericles: API Description A whole API project YOUR PROJECT RESOURCES ATTRIBUTES ROUTES REQUESTS RESPONSES
- 26. 26// Representation of your resource Example - create a user firstname lastname User
- 27. 27// Representation of your resource Example - create a user POST /users - Body of request { "title": "User", "type": "object", "properties": { "firstname": { "type": "string" }, "lastname": { "type": "string" }, "required": ["firstName", "lastName"] } } firstname lastname User
- 28. 28// Representation of your resource Example - get user information GET /users/:id - Body of response { "title": "User", "type": "object", "properties": { "id": { "type": "integer" }, "firstname": { "type": "string" }, "lastname": { "type": "string" }, "age": { "description": "Age in years", "type": "integer", "minimum": 0 }, "required": [“id”,"firstName", "lastName"] } } id firstname lastname age User
- 29. 29// Pericles: API Description A whole API project through representations YOUR PROJECT RESOURCES ATTRIBUTES ROUTES REQUESTS RESPONSES Resource representations
- 30. 30// Pericles: API Description A whole API project through representations YOUR PROJECT RESOURCES ATTRIBUTES ROUTES REQUESTS RESPONSES JSON SCHEMA Collection Resource representations
- 31. 31// 03 // Why is JSON schema still underused?
- 33. 33// Our hero, hidden in the shadows Solution USER SPACE SCHEMA MANAGEMENT
- 34. 34// 04 // What to do with your API defined with schema ?
- 35. 35// Customer, Project Managers Lost of time in trying to replay a use case... My app is crashing again, it’s embarrassing... I’ll take a look at it OK I’m good for an hour to replay this use case, but pretty sure my customer API is faulty
- 36. 36// Test with a proxy Client ServerProxy
- 37. 37// Project Managers, Developers Lost of time in updating thousands of files... So could you please update the specs with the new API specifications please? Sure... I need to modify thousands of files (mocks, doc, …), what a nightmare!
- 40. 40// Customers, Project Managers, Developers Problems solved - time saving for everyone ! My specs are always up to date! When the API is not aligned with the specs I will know it easily! Keeping the specs up to date is now simple!
- 42. 42//