1.
Zeb Mahmood
@zebonic
Alexander Khimich
in/alexanderkhimich

2.
Assumption: This audience understands what’s an API

3.
What do we mean by Enterprise APIs?
Similarities with Public API
 More ‘business’ will be conducted over API than UI
 Security is critical. DDoS attack and un-authorized access are real threats
 Mutations of your application will evolve via its API
 Developers don’t like to read documentation
 You have competition
Internal API
Public API
Private API

4.
Darwin’s theory of natural selection
Evolution of Life:
“Natural selection is a process by which animals and plants
with traits considered desirable by nature
are systematically favored.
Natural selection is thus the key mechanism of evolution for life.”

5.
Darwin’s theory of natural selection
Evolution of Life Applications:
“Natural selection API is a process means by which animals applications and plants
with traits considered desirable by nature developers
are systematically favored.
Natural selection API is thus the key mechanism of evolution for life applications.”

6.
Typical drivers for Enterprise APIs
 Pluggable architecture. Reduce time-to-market. Build fine grain
application UI. For everything else, expose API.
 Monetization. Data is king. Expose your app’s data via API.
 Modernization. Days of file transfers and direct database are over.

7.
The ‘textbook’ recommendations for APIs
 API first
 Single version of APIs
 Always use the right verb
 SOAP/XML is history. Always use REST/JSON

8.
The ‘textbook’ recommendations for APIs
 API first - However, most APIs are retrofitted to old enterprise systems
 Single version of APIs - Hard to avoid while supporting backwards compatibility
 Always use the right verb – But read operations don’t always use POST e.g. search
 SOAP/XML is history. Always use REST/JSON – SOAP is like mainframe. We want to
believe it’s dead. But it’s not!

9.
API first
 Think API first
 Build APIs for internal features
 Eat your own dog food
 Go versioning

10.
API Versioning
 Versioning of URL
 Versioning of API Schema
 Versioning of API business logic
 Versioning of tests/automation
 Versioning of Docs

11.
URL versioning and releases
 Recommendation is to increment versions each major release, regardless if there were
changes or not.
 /v1/contact/{id} - Release 4.0
 /v2/contact/{id} - Release 5.0

12.
{
firstName:”Bob”,
lastName:”Smith”,
middleName:”Tony”
}
V2 request
V2 response
{
fullName:”R A Smith”,
confidence: 0.93
}
API Versioning
V1 request
V1 response
{
firstName:”Bob”,
lastName:”Smith”
}
{
fullName:”Robert Smith”
}

13.
API Versioning
V1 request
V1 response
{
firstName:”Bob”,
lastName:”Smith”,
middleName:”Tony”
}
V2 request
V2 response
{
fullName:”R A Smith”,
confidence: 0.93
}
{
firstName:”Bob”,
lastName:”Smith”
}
{
fullName:”Robert Smith”
}
V1 V2 V3 V4

14.
API Versioning - schema - v1
V1 request
{
fullName:”Robert Smith”
}
V1 response
{
firstName:”Bob”,
lastName:”Smith”
}
Rev1 request adapter
Rev1 Request Object
Business Logic
Rev1 Response Object
Rev1 response adapter
Internal Request Object - 3
fields:[Fname, LName, MName]
Internal Response Object - 2 fields:
[fullName, confidence]

15.
API Versioning - schema - v2
V2 request
{
fullName:”R A Smith”,
confidence:0.93
}
V2 response
{
firstName:”Bob”,
lastName:”Smith”,
middleName:”Tony”
}
Rev2 request adapter
Rev2 Request Object
Business Logic
Rev2 Response Object
Rev2 response adapter
Internal Request Object - 3
fields:[Fname, LName, MName]
Internal Response Object - 2 fields:
[fullName, confidence]

16.
API Versioning - schema - v3
V3 request
{
fullName:”R A Smith”,
confidence:0.93
}
V3 response
{
firstName:”Bob”,
lastName:”Smith”,
middleName:”Tony”
}
Rev2 request adapter knows he can
accept v2 and v3
Rev2 Request Object
Business Logic
Rev2 Response Object
Rev2 response adapter knows he can
accept v2 and v3
Internal Request Object - 3
fields:[Fname, LName, MName]
Internal Response Object - 2 fields:
[fullName, confidence]

17.
API Versioning – Business logic
 Factory design pattern. Get version implementation by version number.
 In code, “if” statements based on version execution context.

18.
API Versioning – Testing
 Black box API testing with version respecting. The same test might be applied to
multiple versions if nothing was changed.
 Test1 - v1
 Test2 - v2* (any after v3)

19.
Documentation
It has to be automatic!
To enable automatic documentation “contract first” development model is preferable.
Some documentation standards to consider
WADL
Swagger
RAML

20.
Sandbox
 It’s a must have for any company
 Worth investing in it
 Should have production SLAs
 Should be treated as production
 API design should respect Sandbox
 Must be easy to try and use
 Right data is a must

21.
Product Owner’s role for Enterprise API’s success
 Recruit early adopters e.g. pilot, beta
 Evangelize to sponsors and champions
 Nurture developer community
 Market via how-to videos, 101 tutorials, hackathons, ….
 Monitor API usage