API-First service design#API_BE @sponnet

@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

@sponnet / #API_BE

ContextThe 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

@sponnet / #API_BE

City portal antwerpen.be

@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

@sponnet / #API_BE

So we have a lot of services

https://www.antwerpen.be/srv/stadsplan/api

@sponnet / #API_BE

And we want to make them public...● API docs● SDK● code

snippets● SASS kit

https://github.com/Antwerp-Operating-System

@sponnet / #API_BE

But the API’s sometimes feel like this

@sponnet / #API_BE

What is API-first development ?

Shared functionality ?- expose this functionality as a

RESTful HTTP API - … to all other developers &

stakeholdersNo shared modules / code bases

@sponnet / #API_BE

API-First design is a paradigm shift

“This is my product”

@sponnet / #API_BE

Net result in a traditional approach

Centralized Engineered system

Subordinate parts serving as means to deliberately designed ends

@sponnet / #API_BE

API-First design is a paradigm shift

“This is my product”

This is a frontend

@sponnet / #API_BE

Net result using an API-First design

decentralized, organic and evolving ecosystem whereindividual actors (API’s ) can be spontaneously enfranchised or co-opted by any other actor / set of actors to serve new purposes.

@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

@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

@sponnet / #API_BE

Benefits on productivity

With solid API’s● Stakeholders can create or hack-together

production ready applications faster● More secure● More reliable

@sponnet / #API_BE

Front-end Frameworks stimulate API use

They enforce the separation of information from presentation through APIs

@sponnet / #API_BE

Webcomponents stimulate API even further

Polymer componentsencapsulates the API as a reusable block too !

@sponnet / #API_BE

API in the product design process

1. well documented2. easy to use3. as conventional as possible4. monitored5. secure6. versioned7. has registry of subscribers

@sponnet / #API_BE

Techniques to implement API-first

@sponnet / #API_BE

Swagger

Simple representation of an RESTful APIhttp://swagger.io/

@sponnet / #API_BE

Swagger Editor

Create and preview your API design→ Creates swagger.json

http://editor.swagger.io/

@sponnet / #API_BE

Swagger UI

documentation , exploration and sandboxing of your API

http://petstore.swagger.io/

@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

@sponnet / #API_BE

Discuss functionalities of the API

nameversionendpointsJSON-schema’sauth. scopes

@sponnet / #API_BE

Definition of API in Swagger editor

create YAML definition preview documentation

@sponnet / #API_BE

Stub your API right from the editor

generates your endpoints andexposes dummy data

explore and publish your API documentation

@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

@sponnet / #API_BE

So what do we have already ?

1. well documented2. easy to use3. as conventional as possible4. monitored5. secure6. versioned7. has registry of subscribers

@sponnet / #API_BE

So what about security / versioning / subscription ?

Out here - we use WSO2 API Manager

API publishingAPI versioningAPI subscriptionsOAuth2 + scopesRouting to backend systems

@sponnet / #API_BE

Thanks!

Stefaan Ponnetstefaan@ponnet.com@sponnet