api world conference
TRANSCRIPT
Zeb Mahmood
@zebonic
Alexander Khimich
in/alexanderkhimich
Assumption: This audience understands what’s an API
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
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.”
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.”
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.
The ‘textbook’ recommendations for APIs
API first
Single version of APIs
Always use the right verb
SOAP/XML is history. Always use REST/JSON
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!
API first
Think API first
Build APIs for internal features
Eat your own dog food
Go versioning
API Versioning
Versioning of URL
Versioning of API Schema
Versioning of API business logic
Versioning of tests/automation
Versioning of Docs
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
{
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”
}
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
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]
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]
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]
API Versioning – Business logic
Factory design pattern. Get version implementation by version number.
In code, “if” statements based on version execution context.
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)
Documentation It has to be automatic!
To enable automatic documentation “contract first” development model is preferable.
Some documentation standards to consider
WADL
Swagger
RAML
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
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