The API-first approach makes an API the first interface built for an application. The approach forces people to build an API that provides high value to the target audience, before building a product on top of it. The OpenAPI Specification (fka Swagger Specification) goes hand-in-hand with an API-first thinking. The OpenAPI Specification enables teams to design a technology-agnostic API interface that is consumer centric and not application biased, while simultaneously keeping your internal stakeholders in sync. In this webinar, we’ll cover what it realistically takes to actually adopt an API-first approach to building products from the API’s design, how to position API design into your development workflow using the latest version of the OpenAPI Specification, OpenAPI 3.0, and effectively collaborate on an actual API design in a real world setting using the OAS and SwaggerHub. Topics covered will include – 1. What is the API-first approach to building applications? 2. What does it take to adopt API-first methodology? 3. What is the OpenAPI Specification (OAS), and what are the newest features of OAS 3.0? 4. How can OAS 3.0 accelerate API development, testing, documentation and delivery in the API-first approach? 5. Real world example of design an actual OAS interface for an API

1. An API First Approach
with OpenAPI 3.0
11.20.17

2. Page 2
@keshinpoint
Product Marketing Manager:
Keshav Vasudevan
@keshinpoint
Marketing Manager:
Ryan Pinkham
Today’s Presenters

3. Page
Try SwaggerHub for free: swaggerhub.com
3
@keshinpoint
Agenda
• WhatistheAPIFirstApproach?
• AdoptingtheAPIFirstapproachintherealworld
• HowcanOpenAPI3.0help?
• HowtocreateanOpenAPI3.0design?

4. What is the API First
Approach?
@keshinpoint
4

5. Page
Try SwaggerHub for free: swaggerhub.com
5
@keshinpoint
Enter the API First Approach
The API First approach involves having your APIs as the first and primary element of your
product and service strategy.
API First means you’re building an API from the ground up to be consumed in an optimal
fashion by client applications and services

6. Page
Try SwaggerHub for free: swaggerhub.com
6
@keshinpoint
Reason 1:Moving Faster
Model Companies

7. Page
Try SwaggerHub for free: swaggerhub.com
7
@keshinpoint
Life In a Monolith
Implementation
API
Backend
Developers
Frontend
Developers
Client A Client B Client C …
Database

8. Page
Try SwaggerHub for free: swaggerhub.com@keshinpoint
Life In a Monolithic Dependency
Stakeholders
Build
Application
Code
Check in to
Repo
Deploy Happy
customers
Test
8

9. Page
Try SwaggerHub for free: swaggerhub.com@keshinpoint
A Monolithic Journey
Stakeholders
Build
Application
Code
Check in to
Repo
Deploy Happy
customers
Test
Codebase 1
9

10. Page
Try SwaggerHub for free: swaggerhub.com@keshinpoint
A Monolithic Dependency
Codebase 1
Codebase 2
Check in to
repo
Deploy
Check in to
repo
Deploy
Codebase 3
Deploy
10

11. Page
Try SwaggerHub for free: swaggerhub.com@keshinpoint
A Nightmare of Failures
Codebase 1
Codebase 2
Check in to
repo
Deploy
Check in to
repo
Deploy
Codebase 3
Deploy
Check in to
repo
Code failure
11

12. Page
Try SwaggerHub for free: swaggerhub.com
12
@keshinpoint
An API First Approach
Backend Developers
Frontend Developers
Client A
Database
Implementation Implementation Implementation
Mock Mock Mock
API API API
Client B Client C

13. Page
Try SwaggerHub for free: swaggerhub.com
13
@keshinpoint
The Jeff Bezos Mandate
Net worth: 95.1 Billion USD
This was issued in 2002!

14. Page
Try SwaggerHub for free: swaggerhub.com
14
@keshinpoint
What CanYou ExpectWith An API First Approach?
Reduced interdependencies, allows teamsto workattheir own pace
Faster development and delivery
Easier expansion to different interfaces,clients and views

15. Page
Try SwaggerHub for free: swaggerhub.com
15
@keshinpoint
Reason 2:Leveraging the API Economy
Model Companies

16. Page
Try SwaggerHub for free: swaggerhub.com
Explosion in the API Economy
0.3 0.6 0.9
1.5
2.4
3.4
7.2
10.3
12.2
14.1
16.1
0
2
4
6
8
10
12
14
16
18
0 2006 07 08 09 10 11 12 13 14 15 16
85%
ofenterpriseswill
haveanAPIby2018
100,000
PublicAPIs
16
@keshinpoint

17. Page
Try SwaggerHub for free: swaggerhub.com
17
@keshinpoint
Platforms Drive The Internet’s GDP
The internet drives over 1.2 trillion Euros in sales
Platform ecosystems
are a major driver of
this growth

18. Page
Try SwaggerHub for free: swaggerhub.com
18
@keshinpoint
API Artifact as Secondary Citizen
• 30%ofworld’scompaniesaretryingtobuildadigitalecosystem
• Platformsaccountforamajorityoftheinternet’srevenue
• APIsarethecenterfoldtoPlatformandAPIEconomy
• APIsdrivingstrategicbusinessgoalswithuniquebusinessmodels

19. Page
Try SwaggerHub for free: swaggerhub.com
19
@keshinpoint
API First Benefits
Reduced interdependencies, allows teamsto workattheir own pace
Faster development and delivery
Easier expansion to different interfaces,clients and views
Developer friendly servicesto build ecosystems and platforms

20. Adopting The API First
Approach
@keshinpoint
2
0

21. Page
Try SwaggerHub for free: swaggerhub.com
21
@keshinpoint
“The definition of insanity is doing the same thing over and over and expecting different results.”
- Albert Einstein
Changing any development approach is not easy!

22. Page
Try SwaggerHub for free: swaggerhub.com
22
@keshinpoint
API First Adoption Guidelines
1. Planning for the Shift
2. Conceptualizing the Service
3. Developing the Service
4. Deploying and Consuming the Service

23. Page
1. Planning the Shift
How does an organization or team plan for the new
approach?
23
@keshinpoint
Topics covered:
• Setting up the team
• Setting up delivery processes
• Setting up guidelines

24. Page
Try SwaggerHub for free: swaggerhub.com
24
@keshinpoint
Planning the Shift:Setting Up Teams and Processes
Setting up the team
• Identify your APIs stakeholders
• Identify your API’s customers
• Set up governance team
Set up a process
• Process is unavoidable, especially for an organization that wants
to scale
• Process needs to be repeatable, realistic and lightweight
• Enforcement usually happens top-down

25. Page
Try SwaggerHub for free: swaggerhub.com
25
@keshinpoint
Example API First Process
Proposal Align Review Design DevelopVerify Deploy
Used by

26. Page
Try SwaggerHub for free: swaggerhub.com
26
@keshinpoint
Planning the Shift:Setting Up Guidelines
WhyGuidelines?
• As APIs areadded to the portfolio, it’simportant to ensure they’re
consistent with each other
• APIs with common behaviors and patternswill easework of
consumers integratingwith them
• New API designs in portfolio won’thave toreinvent wheel
Whatto Coverin Guidelines
• Security
• Naming of resources, parameters,responses
• Error handling
• Dataformat handling
• Versioning

27. Page
Try SwaggerHub for free: swaggerhub.com
27
@keshinpoint
Example Guidelines
Apistylebook.com

28. Page
Try SwaggerHub for free: swaggerhub.com
28
@keshinpoint
API First Adoption Guidelines
1. Planning for the Shift
2. Conceptualizing the Service
3. Developing the Service
4. Deploying and Consuming the Service

29. Page
2. Conceptualizing the Service
How does an organization or team work on a new
service?
29
@keshinpoint
Topics covered:
• Service business objective
• Designing the service
• Virtualizing the service

30. Page
Try SwaggerHub for free: swaggerhub.com
30
@keshinpoint
Conceptualizing the Service:Business Objective of Service
APIsExistFor a Reason
• Identify your organization’s business taxonomy– outer
bounds of business capabilities
• Conceptualize APIs that exist within these bounds
DeterminingWhy API Exists
• What tangible outcome can service bring to overall
business?
• What tangible outcome can service bring to customer?
• What tangible outcome can service bring to internal
processes?

31. Page
Try SwaggerHub for free: swaggerhub.com
31
@keshinpoint
Conceptualizing the Service:The Top Down Approach

32. Page
Try SwaggerHub for free: swaggerhub.com
32
@keshinpoint
Conceptualizing the Service:Design First
• APIFirst and Design First goes hand-in-hand
• Stakeholders (backend, front end, PMs) havefull visibility into what the service is supposed to do
• Puts the business objectiveof the APIfirst before the technology
OpenAPISpec:HumanandmachinereadableinterfaceforRESTAPIs

33. Page
Try SwaggerHub for free: swaggerhub.com
33
@keshinpoint
OAS Opens Up AWorld Of Possibilities

34. Page
Try SwaggerHub for free: swaggerhub.com
34
@keshinpoint
Conceptualizing the Service:Benefits ofVirtualization
• Quicklycreate,edit and use Virtualresponses for OpenAPIs
• Easily record services,modify them and use themfor testing, development, prototyping
• Make virtualservices realistic (reallife)by linking them todata
• Get creativewith routing and dispatching different responses
• Easily route betweenvirtualand actualservice
• Provide accesstothe teamby sharing the virtualizedtransactions
Time Savings Faster Time to Market Full Control

35. Page
Try SwaggerHub for free: swaggerhub.com
35
@keshinpoint
API First Adoption Guidelines
1. Planning for the Shift
2. Conceptualizing the Service
3. Developing the Service
4. Deploying and Consuming the Service

36. Page
3. Developing the Service
How does an organization or team build the service
from the interface?
36
@keshinpoint

37. Page
Try SwaggerHub for free: swaggerhub.com
37
@keshinpoint
Developing the Service
Designand
Documentation
SwaggerHub
Developmentand
Testing
SoapUIServiceV
Mockingand
Virtualization

38. Page
Try SwaggerHub for free: swaggerhub.com
38
@keshinpoint
API First Adoption Guidelines
1. Planning for the Shift
2. Conceptualizing the Service
3. Developing the Service
4. Deploying and Consuming the Service

39. Page
Try SwaggerHub for free: swaggerhub.com
Page
4. Deploying and Consuming the Service
How does an organization or teambuild the servicefrom the
interface?
39
@keshinpoint
Topics covered:
• Cataloging services
• Dev Portal
• Measure the metrics– MaturityModel

40. Page
Try SwaggerHub for free: swaggerhub.com
40
@keshinpoint
Deploying the Service:Catalog Services
WhyCatalog?
• Maybethemost importantpieceofinfrastructureneeded
• Needtoconsolidatediscovery,documentation,SDKs,andoverall
engagement
• Criticalpiecefor internalcommunication
• Centralsourceoftruthalsohelpsenforceotherdevstofollowandintegrate
withAPIs
CatalogMVP
• InventoryofAPIswithownershipinformation
• ShowsallrelevantversionsofanAPI
• Supportscollaborationandaccesscontrol
• Documentationhosting
• SupportsSDKs
• CommunicationandFeedback

41. Page
Try SwaggerHub for free: swaggerhub.com
41
@keshinpoint
Deploying the Service:Measuring Maturity
Whatis aMaturityModel?
• Maturityisameasurementiftheabilityofanorganizationtodeliver
• Inthiscase,howreusableandconsumableAPIis
WhyaMaturityModel?
• API Firstmeansyour APIsarefoundationalpiecesfor anynewproductor service
• APIsmustbeconstantlymeasuresfor effectiveness
• Friendlycompetitionamongteamsleadsto innovate
MaturityModelMetricIdeas
• AccessibilityofAPI
• Speedto first200
• Documentationfriendliness

42. Page
Try SwaggerHub for free: swaggerhub.com
42
@keshinpoint
API First Adoption Guidelines
1. Planning for the Shift
2. Conceptualizing the Service
3. Developing the Service
4. Deploying and Consuming the Service

43. Page
Try SwaggerHub for free: swaggerhub.com
Design First Approach Using
OpenAPI and SwaggerHub
@keshinpoint
43

44. Page
Try SwaggerHub for free: swaggerhub.com@keshinpoint
API First Implementation Using OAS
Design First
Communication and Collaboration
Governance and Guidelines
Mocking and Virtualization
Cataloging and Discovery

45. Page
Try SwaggerHub for free: swaggerhub.com
45
@keshinpoint
The Platform for API First
SwaggerHubis the API designand documentation
platform built for teams to drive consistencyand
disciplineacross their API development workflow.
Faster,Standardized
Design
Centralized,Secure
Collaboration
Hosted,Interactive
Documentation

46. Page
Try SwaggerHub for free: swaggerhub.com
46
@keshinpoint
Let’s Start Designing!
Objective: Design an API that allows users to obtain information for employees, or post
information of new employee in company DB
Team:
- API Designer
- API Documentation
- API Development
- API Governance

47. Page
Try SwaggerHub for free: swaggerhub.com
47
@keshinpoint
Resource: Employee
GET
Gives info for array of employees
Query Parameters
• bodyLimit
• pageLimit
Responses
• 200 Payload
– ID
– Name
– Title
POST
Allows posting info of new employee
Parameters
• Payload
– ID
– Name
– Title
Responses
• 200

48. Thank you!
@swaggerhub
app.swaggerhub.com/help support@swaggerhub.com
swaggerhub.com/blog