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.

1. Managing API
Development
Ciprian Sorlea, CTO
October 2015

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. 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. 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. 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. What can possibly
go wrong?


8. 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

9. 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.

10. But wait, haven’t
we solved this 20
years ago with
UML?

11. 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)

12. Is UML the answer
for our API
management
issues?

13. Could be, but there
is something
better. Better for
API’s.

14. Introducing
RAML

15. 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

16. 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.)

17. 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

18. 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

19. Let’s review our
previous scenarios

20. 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

21. 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

22. 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

23. 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

24. Let’s take a closer
look at RAML

25. 20.11.2015
25
Example:

26. 20.11.2015
26
Traits
Traits define various API behaviors, applicable for one/more/all archetypes:
Ex:
- Paged
- Secured
- Filtered
- WithView
- SupportsPartialRetrieve
- CanBeQueryed

27. 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

28. 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.

29. 20.11.2015
29
Schemas
Already have the JSON request/response structure?
Generate the JSON schema using http://jsonschema.net/ .

30. 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

31. 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

32. 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

33. 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

34. 20.11.2015
34
Where does RAML live?
NEXT TO YOUR CODE

35. 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?

36. 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

37. 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

38. Demo Time

39. Q&A

40. Thanks for watching.
Now go and build
your cool API!