Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Managing api development

826 views

Published on

Developing API's is not as easy as someone might think. A great API is a PRODUCT by itself, so you need to handle it accordingly. Find out some simple way to manage expectations and delivery throughout the development cycle of an API.

Published in: Software

Managing api development

  1. 1. Managing API Development Ciprian Sorlea, CTO October 2015
  2. 2. 20.11.2015 2 Scenario 1 - Dev Team 1 develops the API - Dev Team 2 and Dev Team 3 use the API - QA Team 1 tests the API
  3. 3. 20.11.2015 3 Scenario 2 - Dev Team 1 develops the 1st API - Dev Team 2 develops the 2nd API - Dev Team 3 develops the 3rd API which integrates 1st API and 2nd API
  4. 4. 20.11.2015 4 Scenario 3 - Dev Team 1 develops the API - QA Team tests the API - A new Dev and a new QA join the team
  5. 5. 20.11.2015 5 Scenario 4 - Dev Team 1 develops the 1st API - Dev Team 2 develops the 2nd API - Product Management asks Dev Team 1 and Dev Team 2 to merge the 2 API’s as a public offered API, a new product
  6. 6. What can possibly go wrong? 
  7. 7. 20.11.2015 8 Usual and shared challenges - Different tools and technology stacks used to develop/test/integrating multiple API’s - Different teams involved in development, testing and integrating the API’s - Different experience levels and technical backgrounds - Different code bases - Different initial expectations
  8. 8. 20.11.2015 9 What do we want to achieve? We would like to: - Ensure consistency in API design across all services and products we develop - Ensure we reuse as much knowledge/experience and code as we can - Ensure the communication between various teams is as smooth as possible - Ensure teams can be productive from day one, no matter on which side of the API they are on.
  9. 9. But wait, haven’t we solved this 20 years ago with UML?
  10. 10. 20.11.2015 11 What was UML helping us with? With UML we were able to model various aspects of application design: - Interactions, behaviors and use cases - Structure (classes, components, objects)
  11. 11. Is UML the answer for our API management issues?
  12. 12. Could be, but there is something better. Better for API’s.
  13. 13. Introducing RAML
  14. 14. 20.11.2015 15 What is RAML? - RAML stands for RESTful API Modeling Language - Can be used to define, document & standardize API Definitions - It’s vendor neutral, non-proprietary and specs are open source, and it’s a simple language based on broadly used standards: JSON & YAML - Can be used along with any client/server technologies, for projects ranging from small to large
  15. 15. 20.11.2015 16 What is RAML? - RAML is the best source of truth when it comes to defining the REST API - RAML is the interface and contract established between provider (implementation/server) and consumer (client app, 3rd party app, mobile app, QA Automation Scripts, etc.)
  16. 16. 20.11.2015 17 RAML Specification Lifecycle - The team establishes best practices and patters and identifies the resource types (archetypes) and traits to be defined. This defines the API standard - Each endpoint is associated with the required resource types and traits - Any deviation/customization from the standard offered by the resource types and traits can be achieved through overriding and extension - The API contract is therefore being built, based on the agreed standard
  17. 17. 20.11.2015 18 RAML Specification Lifecycle - Provider team develops the API Contract (RAML) according to the established API standards - Provider team implements the API according to the contract - Consumer team use the API based on the contract - QA team implements the Automation Tests according to the contract
  18. 18. Let’s review our previous scenarios
  19. 19. 20.11.2015 20 Scenario 1 - Dev Team 1 develops the API according to the RAML contract - When the API is Ready - Dev Team 2 and Dev Team 3 use the API, using the RAML contract (documentation/specification) - QA Team 1 build the automation scripts using the RAML contract and they test it against the real API - While the API is in development - Dev Team 2 and Dev Team 3 use the mockup API service, generated using the RAML contract (documentation/specification) - QA Team 1 build the test automation scripts using the mockup API Service, and then test it against the real API once it becomes available
  20. 20. 20.11.2015 21 Scenario 2 - Dev Team 1 develops the 1st API according to the agreed API Standard - Dev Team 2 develops the 2nd API according to the agreed API Standard - Dev Team 3 develops the 3rd API which integrates 1st API and 2nd API, without any issue, because both API’s are using the same standard
  21. 21. 20.11.2015 22 Scenario 3 - Dev Team 1 develops the API, according to the agreed API Standard, using the RAML contract - QA Team tests the API, based on the RAML contract - A new Dev and a new QA join the team. They are quickly ramped up on the agreed API standards and existing API specifications defined in the RAML contract
  22. 22. 20.11.2015 23 Scenario 4 - Dev Team 1 develops the 1st API, according to the agreed API Standard - Dev Team 2 develops the 2nd API, according to the agreed API Standard - Product Management asks Dev Team 1 and Dev Team 2 to merge the 2 API’s as a public offered API, a new product. This is now possible because the new API Product will follow the same API Standard, and the merge is now much easier
  23. 23. Let’s take a closer look at RAML
  24. 24. 20.11.2015 25 Example:
  25. 25. 20.11.2015 26 Traits Traits define various API behaviors, applicable for one/more/all archetypes: Ex: - Paged - Secured - Filtered - WithView - SupportsPartialRetrieve - CanBeQueryed
  26. 26. 20.11.2015 27 Traits Once a behavior is defined, consistency is ensured in usage: - same parameters will be used for pagination in all API’s as well as all tests, client frameworks, etc. In addition, it’s much clear what can you do with a resource model
  27. 27. 20.11.2015 28 Schemas • Schemas are used to define our resource models • RAML Schemas are extensions of JSON Schema and XML Schema • Schemas provide means to quickly validate data but also to proactively build integrations and clients based on know facts • Not all custom validation rules can be defined using schema support, so the right description for each field with custom rules should be defined in readable form.
  28. 28. 20.11.2015 29 Schemas Already have the JSON request/response structure? Generate the JSON schema using http://jsonschema.net/ .
  29. 29. 20.11.2015 30 Resource Types • Resource Types represent the Archetype (API Architecture) templates • Each Resource Type can be applied for any number of Resource Models, as long as the behavior is inherited • Each resource model can use a single Resource Type • Resource Types use traits to reuse behaviors and schemas to specify the resource models being used
  30. 30. 20.11.2015 31 Examples • RAML can include examples of requests / responses, to showcase the usage of the API • The examples can be provided for regular flows or for exception / error flows • Examples can also be provided for XML or JSON content types
  31. 31. 20.11.2015 32 Includes • Includes allow certain API standards (resource types and traits) to be reused among products / projects • They also reduce the code complexity on large API definitions • Included RAML files can be hosted online or next to the files that use them
  32. 32. 20.11.2015 33 Editing RAML • RAML can be edited with any popular IDE / Editor • Works with IntelliJ/WebStorm, Visual Studio, Atom, Sublime • Any editor with support for YAML can edit RAML • Certain extensions / plugins might be needed to enable support or auto- completion
  33. 33. 20.11.2015 34 Where does RAML live? NEXT TO YOUR CODE
  34. 34. 20.11.2015 35 Where does RAML live? So, we have our API Standard and our RAML contract. Can we do anything else with it?
  35. 35. 20.11.2015 36 RAML usage scenarios With RAML you can: - Generate API Documentation (see https://github.com/kevinrenskers/raml2html ) - Generate Mockup API Service (see https://www.npmjs.com/package/raml-mockup and https://github.com/farolfo/raml-server) - Generate boilerplate code using specific parsers for PHP, Ruby, Java, .NET & Javascript (see http://raml.org/projects.html ) - this can include, but is not limited to: - API Controllers - API Client Libraries
  36. 36. 20.11.2015 37 RAML usage scenarios With RAML you can: - Load it in Postman or SoapUI and immediately start playing with the API - Automate validation of the API and documentation generation using GULP
  37. 37. Demo Time
  38. 38. Q&A
  39. 39. Thanks for watching. Now go and build your cool API!

×