TOOL CHAINS IN API DESIGNSCOTT COLESTOCK

AGENDA

WHAT ARE WE GOING TO TALK ABOUT?

▸ "First class” APIs versus “just your own backend"

▸ A C# Service, Swagger-enabled

▸ APIs with a “Design-First” mindset…using Swagger “inside out”

▸ (There are options beyond Swagger, of course - we’re focusing there for simplicity)

▸ What does design-first thought buy you?

▸ Collaboration / validation / testing

▸ Moving to microservices / serverless

FIRST CLASS APIS

APIS FOR THE SERVICES YOU LIKE…

▸ https://auth0.com/docs/api/authentication

▸ https://www.zoho.com/subscriptions/api/v1

▸ https://www.contentful.com/developers/docs/references/content-delivery-api/

▸ https://developer.intuit.com/docs/api/accounting/invoice

▸ Feels a bit dated: http://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGET.html

FIRST CLASS APIS

IF APIS ARE A CORE VALUE PROPOSITION…THEN DOCS…

▸ Will have good introductions & remarks to describe the finer points of the service

▸ Will be rich with example requests and responses

▸ Will have field-level explanations of the semantics of the content

▸ Will have ability to invoke a service directly (sandbox)

▸ Will show invocations from a variety of languages (working samples)

programmableweb.com / January 2013

API COMMUNITY SURVEY

FIRST CLASS APIS

JUST YOUR OWN BACKEND ?

▸ Many services evolve from a gradual drip of requirements to satisfy particular mobile / web needs

▸ They are essentially a private handshake - even if designed with restful patterns in mind

▸ Inbound and outbound payload shapes require insider knowledge to understand (required vs optional, etc.)

▸ Effects of parameterization on the behavior require insider knowledge

▸ (You need to look at an existing client or the server code to truly understand semantics)

▸ Often suffer from poor factoring - just “one more option” added over time

▸ When you’re asked to expose your API to others, it becomes clear too much tribal knowledge is required…

EVOLVING THE API LIFECYCLE TO GET BETTER AT THIS…

WHAT WOULD THAT LOOK LIKE ?

CODE FIRST: C# WEB API

DAY IN THE LIFE OF A SERVICE DEVELOPER?

DESCRIBING SERVICES…

DESCRIBING SERVICES

SOME HISTORY…

▸ We’ve been doing distributed request-response patterns (practical implementations) since the 1980s

▸ Sun’s RPC (Remote Procedure Call) protocol

▸ Once we had OO, we decided “remote method invocations” were more interesting (CORBA & DCOM in 90s - objects over the wire) - both built on top of RPC mechanisms

▸ All required a machine-readable interface file…

[object, uuid(a03d1420-b1ec-11d0-8c3a-00c04fc31d2f),] interface Breakfast : IUnknown

{

HRESULT MethodA([in] short Bread, [out] BKFST * pBToast);

HRESULT MethodB([in, out] BKFST * pBPoptart);

};

DESCRIBING SERVICES

SOME HISTORY…

▸ With the internet, all the “firewall unfriendly” protocols became too high friction, and so…

▸ XML-RPC (1998)

▸ No machine readable interface language needed - it’s self describing…

▸ SOAP (1999-2009)

▸ WSDL (Web Services Definition Language) & XSD to form a machine readable interface file

▸ REST (2000)

▸ No machine readable interface language needed - it’s self describing…

DESCRIBING SERVICES

ANOTHER PENDULUM SWING

▸ Arguably, this go-around is about enabling a much richer ecosystem than just client proxy generation

▸ (We’ll see examples shortly)

‣ 2009: WADL (dead)

‣ 2010: Swagger*

‣ 2013: API Blueprint

‣ 2013: RAML

Name origin: Zeke Sikelianos, “Why WADL when you can Swagger?"

DESCRIBING SERVICES…

SWAGGER: MACHINE-READABLE INTERFACE FILES FOR REST

▸ History: In 2010 work started by Wordnik

▸ 2015: Parent company Reverb sold to SmartBear (SoapUI)

▸ 2016: SmartBear formed “Open API” initiative (sponsored by Linux Foundation) and donated Swagger (& renamed)

▸ Swagger/OpenAPI is a specification for describing, producing, and consuming REST services

▸ Original goals:

▸ “Enable clients and documentation systems to update at same pace as server implementation.”

▸ “Documentation of methods, parameters, models tightly integrated into the server code”

DESCRIBING SERVICES…

SWAGGER

▸ A server exposes (json-based) descriptions of:

▸ Endpoint

▸ Resources (like /account)

▸ Operations (GET/POST)

▸ Full payload information (parameters, models). See here.

▸ Traditionally, your server implementation generates swagger json using a framework

▸ Swagger UI will auto-generate documentation & test invocation ability (UI sometimes embedded in framework)

C# WEB API - ADD SWAGGER

DESCRIBING SERVICES

OVERLY-INVESTED ?

▸ For a very simple service, I’ve done a fair bit of work to…

▸ Model my intended payloads in C#

▸ Document my service (in C#)

▸ Create examples (in C#)

▸ As we take in feedback on our service, each iteration is a deployment cycle - not a very fast feedback loop

▸ Service design should be lower friction than this - hence emerging notion of “design-first”

(If you're response is ‘I agree, so I always start on a napkin or a wiki’, then you’ll be interested in the rest of the discussion)

DESIGN FIRST

WHAT DOES THAT MEAN?

▸ Many shops doing REST services will work through resource names, URI structure, etc.

▸ “Design First” thought goes further - designing the set of services required to a solve a set of use cases in detail - before coding

▸ What do the request/response payloads look like? (Write down what will be on the wire)

▸ How are query parameters used?

▸ What is required versus optional ? What triggers various HTTP responses?

DESIGN FIRST

NEW TOOLS

▸ Growing realization that API should be treated as a product in & of itself, with developer success as key metric

▸ Several vendors have moved to create tools to enable “design first” creation of APIs along with all the benefits that should bring:

▸ “Pre-coding” mock implementations

▸ Documentation generation (pre-code)

▸ Test generation

▸ Client wrapper generation / server scaffolding generation

SWAGGER TOOLS

SWAGGER CODEGEN

SWAGGER HUB

(COMMERCIAL)

SWAGGERUI

SWAGGER EDITOR

(FREE & OPEN SOURCE)

(Demo…)

TEXT

YAML REFRESH

▸ “Yet another markup language" → “YAML Ain’t Markup Language”

▸ YAML: Human readable data serialization language

▸ Superset of JSON - option to use indentation instead of braces/brackets

▸ Scalars, lists, associative arrays

▸ Whitespace indentation for structure - but not tabs

▸ # for comments

▸ - for lists, one per line (or enclosed in [] with commas)

▸ : (colon space) for associative arrays, one per line (or enclosed in {} with commas)

▸ | to preserve newlines in blocks, > to fold newlines

▸ Designate repeating node like bill-to: &id001, reference later with ship-to: *id001

▸ --- to separate multiple documents, … to optionally end a document

▸ Rich data types - beyond json (sets, ordered and unordered maps, etc.)

API GATEWAYS

USING SWAGGER TO DRIVE AWS API GATEWAY

▸ Now that you have a formal machine-readable description of your service…

▸ Now that you have a formal artifact that stands apart from any particular code implementation…

▸ You can use something like AWS API Gateway to get

▸ Throttling

▸ Authentication

▸ Schema validation

▸ DDOS protection

▸ Per method configuration of implementation (hello microservices)

API GATEWAYS

THANKS. QUESTIONS ?

Scott Colestock

ALL DONE…

EXTRA

DESIGN FIRST

WHAT DOES DESIGN-FIRST PROCESS LOOK LIKE?

▸ Avoid the design of your APIs as SQL over HTTP…don’t expose internal implementation detail

▸ Capture & validate real use cases for how your API will be consumed (ask real developers to try a scenario out in client code - observe, don’t direct)

▸ Name everything from customer perspective - not your internal convention

▸ Let the API represent “ideal state” - not what will be easy based on internal implementation. (Make ideal for consuming developer)

▸ Document your patterns (naming conventions, URI schemes, paging, etc.) so you can maintain consistency

▸ Share your design with an API portal tool (like Swagger UI)

https://www.infoq.com/presentations/api-design-first

DESIGN FIRST

SWAGGER USING A TYPICAL APPROACH…

▸ Swagger docs generated from service’s implementation code

▸ All additional comment-sourced docs live with the service code

▸ All example request/responses generated by code

▸ But…the commitment to have API documentation should enable validating API design prior to implementation…

▸ So, last few years has brought a push for a “Design First” mindset for APIs…

DESIGN FIRST

WHAT SAY SWAGGER? “YOU SHOULD USE DESIGN FIRST WHEN…”

▸ When Developer Experience Matters

▸ “A well designed API can do wonders for the adoption and consumption of your APIs, and good design can be better achieved with the Design First approach.”

▸ When Delivering Mission Critical APIs

▸ The biggest reason to go for the Design First approach is when your API’s target audience are external customers or partners…

▸ When Ensuring Good Communication

▸ Identifying bugs and issues in the API’s architecture with your team becomes easier when inspecting a human-readable design. Spotting issues in the design, before writing any code is a much more efficient and streamlined approach, than doing so after the implementation is already in place.

https://swaggerhub.com/blog/api-design/design-first-or-code-first-api-development/

TEXT

SWAGGERHUB

▸ “SwaggerHub is an online platform where you can design your APIs and collaborate on them using Swagger”

▸ Core principle: Design First, Code Later. Start by laying out your API, its resources, operations and data models

▸ API Definition → generated clients, generated servers, mock servers, Swagger UI, API Gateway, etc.