API Languages & Contract-First Design

John Zaccone - Software Engineerhttp://www.ipponusa.com

Overview

● API Documentation Languages

● Demo

● Contract-First Design

● Refactor the Demo

● Cool Tools

2

Let’s REST together

3

We need Documentation for our REST APIs

● API Doc Languages define a specification

● Specifications are Machine-Readable

● Parsers and tools that understand the specification can provide great features for little work

4

Value Added

● API Doc specifications are open-source

● Value comes from suite of tools and parsers build on that specification

● Interactive documentation, code generation, postman collections, mock servers, traffic inspection, API testing and analytics and much, much more

5

Bottom Up or Top Down

● Top-down (aka contract-first)

○ Write doc first

○ Generate code from docs

● Bottom-up

○ Write code first

○ Generate docs from code

6

Comparing What’s Out There

Swagger RAML API Blueprint

Sponsored By Reverb Mulesoft Apiary

Initial Commit July, 2011 Sep, 2013 April, 2013

Designed For Code First Contract First Contract First

Workgroup Yes Yes No

Format JSON w/ YAML YAML Markdown

Community 2,386 942 1,614

7

Modeling REST

They all support:

● Resources● HTTP Methods● Query Parameters● URL Parameters● Header Parameters● Status Codes, Content-Types

8

Modeling REST

Swagger RAML API Blueprint

Authentication Basic, API-Key, OAuth2

Basic, Digest, OAuth1, OAuth2

Basic, API-Key, OAuth2

File Inclusions Yes, $ref Yes

Nested Resources Yes Yes

API Versioning Yes Yes

Sample Representations

Yes Yes

9

Integrations ⭑

Swagger RAML APIBlueprint

Server-Side java, scala, ruby, nodejs

java

Client-Side scala, flash, java, objc, php, python,

ruby

js

Parsers js, java js, java c++, .net, ruby

10

Overview

● API Documentation Languages

● Demo

● Contract-First Design

● Refactor the Demo

● Cool Tools

11

Pet Store API

● Get all Pets

● Add a Pet

● Get Pet by ID

● Paging and Security

12

A History

● Swagger starts in July 2011, provides API documentation automatically from code

● Push for “contract-first” design

● RAML (Sept, 2013) found that Swagger “was best suited for documenting an existing API, not for designing an API from scratch”

● Swagger 2.0 addresses contract-first design weaknesses (~Sept, 2014)

13

Overview

● API Documentation Languages

● Demo

● Contract-First Design

● Refactor the Demo

● Cool Tools

14

Contracts Are Valuable

● Enable 3rd-party developers to build awesome apps

● Channel of revenue

● Drive innovation by sharing internal APIs

● APIs are enablers

15

16

Problems

● Doesn’t consider needs of consumers

● Not-so-nice APIs

○ Complicated models

○ Unfriendly business logic

● Consumers might have a different view of the world

17

18

API Facade Pattern

● Hide the complexity

● Define an API that users want to use

● Simple models

● Consistent interfaces

19

Agile in API Design

20

Contract-First

Swagger RAML API Blueprint

Language Writability

Good Good Good

Re-usable Patterns

Good Great OK

Mock Server 3rd Party Yes Yes, External Tool

Collaboration Platform

Open-Source Solution?

Enterprise Offering Enterprise Offering

21

Common Patterns in REST

● Many patterns of REST are repeated over and over...

● Get /my_collection

● Post /my_collection

● Filtering, ordering and paging

22

Patterns with RAML

● ResourceTypes define common behaviors for resources

● Traits define common behaviors for methods

● Example: /petstype: collection

23

Overview

● API Documentation Languages

● Demo

● Contract-First Design

● Refactor the Demo

● Cool Tools

24

Take Away

● Swagger wins

○ Community support

○ Extensive client-side and server-side integrations

● RAML wins

○ Advanced re-use patterns for resources and methods

○ Supports multiple files, and enterprise solution for collaboration

○ Great for designing APIs from scratch

25

Keep an Eye Out...

● Community growth in RAML

● Better ways to write APIs in Swagger

● @swagger, @mulesoft

● swagger2raml, raml2swagger

26

Overview

● API Documentation Languages

● Demo

● Contract-First Design

● Refactor the Demo

● Cool Tools

27

Client SDK Generator

● https://github.com/swagger-api/swagger-codegen

● Supports a growing list of languages

28

RAML API Designer with MongoDB

● https://github.com/brianmc/raml-store

29

Enterprise Solutions

● RAML (https://anypoint.mulesoft.com)

● API Blueprint (http://apiary.io/)

30

Verify Code == Docs

● Aboa: (https://github.com/cybertk/abao)

● Dredd: (https://github.com/apiaryio/dredd)

● Command-line tool to check if service implementation matches RAML doc

● Integrate into your CI (Jenkins) Build

31

API Mashups

● API Notebook (https://api-notebook.anypoint.mulesoft.com)

● Live javascript

● Quickly create clients from RAML definitions

● Make PoC and prototypes

● Saved as Github Gists

32

Other

● RAML and Swagger imports into your Postman client

● Sublime plugin for API Blueprint and RAML

● raml2html (https://github.com/kevinrenskers/raml2html)

33

Questions

?jzaccone@ipponusa.com

@JohnZaccone

34

References

● https://speakerdeck.com/apistrat/another-api-blueprint-raml-and-swagger-comparison

● https://blog.soa.com/spread-the-wealth-developer-communities-for-your-apis-part-2-top-down-or-bottom-up-structuring-your-community/

● https://www.youtube.com/watch?v=vu8_QLkW1mg

● http://apiux.com/2013/04/09/rest-metadata-formats/

● http://stackoverflow.com/questions/26917188/how-to-break-swagger-2-0-json-file-into-multiple-modules/26917653#26917653

● http://raml.org/spec.html

● http://stackoverflow.com/users/1103327/ron?tab=answers&sort=votes (Swagger Questions)

● http://www.programmableweb.com/news/reverb-apigee-announce-swagger-2.0-workgroup/2014/05/23

● http://forums.raml.org/t/how-is-this-different-from-swagger/24

● https://github.com/swagger-api/swagger-spec/wiki/Swagger-1.2-to-2.0-Migration-Guide

35