The motivation on why and when to use API-First service design. What are the real-life poblems in application development with regard to API's ? And how to solve these using tools like Swagger Editor , Swagger UI and Swagger-codegen. And how can an API Manager tool help to manage the Apllication Lifecycle of your API ( publishing , versioning, registration of consumers , quota's and rate-limiting )

1. API-First service design
#API_BE @sponnet

2. @sponnet / #API_BE
Context
@Digipolis Antwerp, IT-partner city of Antwerp
Aims to build an open source and user-centric
city platform as a foundation layer for
personalised and any-device public services

3. @sponnet / #API_BE
Context
The architecture should be open, modular and layered to
allow optimal integration in existing environments and
scaling for performance.
Reusable services, an open SDK and API’s accelerate the
development, maximize integration and reduce the time to
market.
To be built in co-creation with freelancers, start-ups,
students, creatives...
You can participate! Go to http://antwerpen.digipolis.be

4. @sponnet / #API_BE
City portal antwerpen.be

5. @sponnet / #API_BE
Built using
● PHP ( authentication / user management /
apps )
● NodeJS ( several apps )
● AngularJS (1.2 , but we’re migrating to 1.4)
Redis - MongoDB - nginx - Solr

6. @sponnet / #API_BE
So we have a lot of services
https://www.antwerpen.be/srv/stadsplan/api

7. @sponnet / #API_BE
And we want to make them public...
● API docs
● SDK
● code
snippets
● SASS kit
https://github.com/Antwerp-Operating-System

8. @sponnet / #API_BE
But the API’s sometimes feel like this

9. @sponnet / #API_BE
What is API-first development ?
Shared functionality ?
- expose this functionality as a
RESTful HTTP API
- … to all other developers &
stakeholders
No shared modules / code bases

10. @sponnet / #API_BE
API-First design is a paradigm shift
“This is my product”

11. @sponnet / #API_BE
Net result in a traditional approach
Centralized Engineered system
Subordinate parts serving as means
to deliberately designed ends

12. @sponnet / #API_BE
API-First design is a paradigm shift
“This is my product”
This is a frontend

13. @sponnet / #API_BE
Net result using an API-First design
decentralized, organic and evolving ecosystem where
individual actors (API’s ) can be spontaneously
enfranchised or co-opted by any other actor / set of actors
to serve new purposes.

14. @sponnet / #API_BE
Enterprises have a long way to go
No API guidelines
API’s are an aftertought
API design is not part of a functional analysis

15. @sponnet / #API_BE
Opportunities of using well designed
& documented API’s
● speed of development
● stimulates re-use
● de-centralized
● evolves towards an ecosystem of services
● organic and always evolving
● easily co-opted by other actors

16. @sponnet / #API_BE
Benefits on productivity
With solid API’s
● Stakeholders can create or hack-together
production ready applications faster
● More secure
● More reliable

17. @sponnet / #API_BE
Front-end Frameworks stimulate API use
They enforce the
separation of
information from
presentation
through APIs

18. @sponnet / #API_BE
Webcomponents stimulate API even further
Polymer components
encapsulates the API as a reusable block too !

19. @sponnet / #API_BE
API in the product design process
1. well documented
2. easy to use
3. as conventional as possible
4. monitored
5. secure
6. versioned
7. has registry of subscribers

20. @sponnet / #API_BE
Techniques to implement API-first

21. @sponnet / #API_BE
Swagger
Simple representation of an RESTful API
http://swagger.io/

22. @sponnet / #API_BE
Swagger Editor
Create and preview your API design
→ Creates swagger.json
http://editor.swagger.io/

23. @sponnet / #API_BE
Swagger UI
documentation , exploration and sandboxing of
your API
http://petstore.swagger.io/

24. @sponnet / #API_BE
Swagger-codegen
Generates :
- API servers & clients in various languages
and for various frameworks
- C# / JavaScript ( NodeJS ) / GO / ...etc.
- Static HTML documentation
https://github.com/swagger-api/swagger-codegen

25. @sponnet / #API_BE
Discuss functionalities of the API
name
version
endpoints
JSON-schema’s
auth. scopes

26. @sponnet / #API_BE
Definition of API in Swagger editor
create YAML definition
preview documentation

27. @sponnet / #API_BE
Stub your API right from the editor
generates your
endpoints and
exposes dummy data
explore and publish your API documentation

28. @sponnet / #API_BE
Deploy our stub to start
development
backend DEV starts
implementing
business logic for
your backend
frontend DEV uses stubbed API to design his
front-end / routing logic etc.
Towards a mutual result

29. @sponnet / #API_BE
So what do we have already ?
1. well documented
2. easy to use
3. as conventional as possible
4. monitored
5. secure
6. versioned
7. has registry of subscribers

30. @sponnet / #API_BE
So what about security / versioning / subscription ?
Out here - we use WSO2 API Manager
API publishing
API versioning
API subscriptions
OAuth2 + scopes
Routing to backend systems

31. @sponnet / #API_BE
Thanks!
Stefaan Ponnet
stefaan@ponnet.com
@sponnet