This document summarizes the state of web API languages in 2016. It discusses how OpenAPI Specification (OAS), RAML, and API Blueprint are the main API description languages, with OAS having the strongest market traction and an upcoming 3.0 version. It also outlines maturity levels for API languages from describing API contracts to implementing and operating APIs. Finally, it discusses challenges around converging on common standards and integrating API design, testing, and operations workflows.

1. The State of Web API
Languages in 2016
Jerome Louvel, Chief Geek
@jlouvel

2. © Restlet 2016
x
© Restlet 2016
Jérôme LOUVEL
About Jérôme LOUVEL
• Founder, CTO & VP of Products at Restlet
• Restlet Framework creator,
first REST framework for Java (2004)
• Contributor to “RESTful Web Services” (O’Reilly, 2007)
• Member of JAX-RS 1.0 expert group (2007 - 2009)
• Co-author of “Restlet in Action” (Manning, 2012)
• InfoQ editor covering Web APIs (since 2014)
• Board member of Open API Initiative
@jlouvel

3. © Restlet 2016
x
© Restlet 2016
• New API Use Cases
• Continuous API Delivery
• API Team Collaboration
Why API Languages?

4. © Restlet 2016
API Use Cases
API centric
software
Mobile app
backend
IoT
backend
Micro
service
Web app
backend
Social bot
backend
Partner
API
gateway
Public
API
gateway
Automated
workflow

5. © Restlet 2016
Continuous API Delivery
DEV
API centric
software
QA
OPS
BIZ

6. © Restlet 2016
1 | Code-first & Provider driven
Provider
team
Consumer
teams
API
Impl
SDK
Client
A
SDK
Client
B
...
...
3
1
2

7. © Restlet 2016
2 | Contract-first & Provider driven
Provider
team
Consumer
teams
Impl
SDK
Client
A
SDK
Client
B
...
...
2
1
Mock
2
API

8. © Restlet 2016
3 | Collaborative Contract-first
Provider
team
Consumer
teams
Impl
SDK
Client
A
SDK
Client
B
...
...
2
1
Mock
2
API

9. © Restlet 2016
4 | Contract-first & Consumer Driven
Provider
team
Consumer
teams
Impl
SDK
Client
A
SDK
Client
B
...
...
2
1
Mock
2
API
Mock
API
Impl
Mock
API
Impl
ServicesData

10. © Restlet 2016
5 | Contract-first & Consumer Owned
Provider
team
Consumer
teams
Impl
SDK
Client
A
SDK
Client
B
...
...
2
1
Mock
2
API
Mock
API
Impl
Mock
API
Impl
Data Services

11. © Restlet 2016
API Team Collaboration
API
Team

12. © Restlet 2016
Impact on API development
• New types of APIs
- internal & external APIs
- mini & micro APIs
- experience APIs
• Number of APIs increases
- channels growth
- history of versions
- microservices pattern
- quality of service
• → Industrialization needed
- automated workflows
- better tooling
- importance of API languages
API Platform
Micro APIs
(domain data & logic)
Mini APIs
(domain services)
Experience APIs
(backends)
User Interfaces
(frontends)
Public APIs
(gateways)
End-users
Micro APIs
(external SaaS)
Partner devs

13. © Restlet 2016
x
© Restlet 2016
• OAS
• RAML
• API Blueprint
• Alternatives
Which API Language?

14. © Restlet 2016
Current state
• Version 2.0 widely adopted with strong tooling support (fka Swagger Spec)
• Basis of contribution to the OpenAPI Initiative (OAI)
• Strongest market traction
Upcoming 3.0 version
• Structural improvements
• Request Parameters
• Protocol and Payload
• Documentation, Security, Path definitions
• Release planned for first half of 2017
Learn more
• https://www.openapis.org/blog
• https://www.openapis.org/specification/repo
• https://www.infoq.com/news/2016/01/tony-tam-oai-initiative-swagger
• https://www.infoq.com/articles/open-api-initiative-update
OpenAPI Specification (OAS)

15. © Restlet 2016
Content, Callbacks, Links, etc.
Overview of changes in OAS 3.0

16. © Restlet 2016
Evolution of Swagger
2015
Specification
donated
Open source
framework
Commercial
cloud tool

17. © Restlet 2016
Current state
• Version 0.8 adopted with good tooling support
• Good market traction, especially in larger enterprises
• Strong support by MuleSoft, a well established software vendor
Latest 1.0 version
• Built-in data typing, examples, libraries, annotations, overlays and extensions
• Stronger design and reusability capabilities than OAS
• Tooling partially available but progressing
Learn more
• http://www.raml.org/
• https://github.com/raml-org/raml-spec/
• https://www.infoq.com/news/2016/08/raml-1.0-mulesoft
RESTful API Modeling Language (RAML)

18. © Restlet 2016
Current state
• Version 1A9 adopted with good tooling support
• Good market traction, especially during by API design teams
• Support by Apiary, an API startup
Latest version
• Built-in data typing based on Markdown → MSON
• Still young compared to more mature schema languages such as JSON Schema
• ABP creator, Zdenek Nemec, recently left Apiary → see his talk at APIdays on what’s next
• Apiary is a member of OAI and also supports OAS in its tooling
Learn more
• https://apiblueprint.org/
• https://github.com/apiaryio/api-blueprint/
• https://www.infoq.com/news/2015/05/api-blueprint-progress
API Blueprint

19. © Restlet 2016
• RAPID-ML
- Created by RepreZen
- Data/Domain-Driven API Modeling
- RepreZen API Studio
• Google API Discovery format
- Supports Google Discovery Service
- Not used elsewhere much
- Google is a founding member of OAI and supports OAS
• WADL
- The pioneer, created by Sun Microsystems in 2005
- XML based alternative to WSDL
- Still used in Apigee products for example
Alternatives

20. © Restlet 2016
Languages are Abstraction Layers
Hardware
Assembly languages
System languages
Application languages
Web API languages
software level, drivers
NASM / TASM
OS level, high performance
C / C++ / C# / Go
productivity, portability, business logic
Java / PHP / Visual Basic
web scale, interoperability, integration, DSLs
OAS / RAML / API Blueprint
lowest level, machine code
x86 / CISC / RISC / etc.
1st generation
2nd generation
3rd generation
4th generation
3rd generation

21. © Restlet 2016
Maturity levels of API Languages
• 1) Describe API contract
- endpoints, resources, operations, representations
- enable the generation of:
• client SDKs & server skeletons
• documentation
• test scenarios
• mock servers
• 2) Implement API
- wrap regular applications written with classic languages
- compose lower-level APIs into higher-level APIs
- integration purpose at web scale
• 3) Operate API
- provide the infrastructure to deliver the API
Lower level
languages
API delivery
network

22. © Restlet 2016
x
© Restlet 2016
• For Design
• For Testing
• Maturity levels
API Language IDEs

23. © Restlet 2016
Design IDE - SmartBear SwaggerHub

24. © Restlet 2016
Design IDE - MuleSoft API Designer

25. © Restlet 2016
Design IDE - Apiary Editor

26. © Restlet 2016
Design IDE - Restlet Studio

27. © Restlet 2016
Design IDE - Restlet Studio

28. © Restlet 2016
Test IDE - Postman

29. © Restlet 2016
Test IDE - Paw

30. © Restlet 2016
Test IDE - Restlet Client (DHC)

31. © Restlet 2016
API Centric Software - Maturity Levels
Level 4
Behavior driven
Level 3 - Test driven
(replace UI testing, blue green deployment)
Level 2 - Contract driven
(provider driven, collaborative, consumer driven)
Level 1 - Implementation driven
(code driven, data driven, service driven)
API centric software is software

32. © Restlet 2016
Our API challenges
● 1 | Converge API languages
○ OpenAPI Initiative as standardization body
○ extend OAS with specialized languages (design, testing, operation)
○ move innovation to upper levels
○ accelerate tooling ecosystem
● 2 | Better API workflows
○ integrate API & DevOps tools
○ integrate Design & Test
○ integrate Design & Operate
○ Integrate Test & Operate
→ A whole new API Stack is emerging!

33. Thank you
Q&A