Managing API Development

Ciprian Sorlea, CTOOctober 2015

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

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

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

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

What can possibly go wrong?

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

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.

But wait, haven’t we solved this 20

years ago with UML?

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)

Is UML the answer for our API

management issues?

Could be, but there is something

better. Better for API’s.

Introducing

RAML

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

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

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

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

Let’s review our previous scenarios

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

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

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

Let’s take a closer look at RAML

20.11.2015 25

Example:

20.11.2015 26

Traits

Traits define various API behaviors, applicable for one/more/all archetypes:

Ex:

- Paged

- Secured

- Filtered

- WithView

- SupportsPartialRetrieve

- CanBeQueryed

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

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.

20.11.2015 29

Schemas

Already have the JSON request/response structure?

Generate the JSON schema using http://jsonschema.net/ .

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

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

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

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

20.11.2015 34

Where does RAML live?

NEXT TO YOUR CODE

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?

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

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

Demo Time

Q&A

Thanks for watching.

Now go and build your cool API!