Upload
scolestock
View
305
Download
3
Embed Size (px)
Citation preview
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)
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…
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)
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)
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.