An overview of 5 new API design trends. For each, I briefly summarize, show sample code, insert community opinions, showcase open source tooling, and find examples. - Developer Experience - GraphQL - AsyncAPI - OpenAPI Specification - OAuth & OpenID Connect

1. BILL
DOERRFELD
@DoerrfeldBill
Austin API
Summit 2019
A Snapshot of API Design
Trends In 2019

2. Nordic APIs Community
API Tooling, Vendors
API Consumers, Developers
Thought Leaders, Bloggers
API Owners, Practitioners
Blog, Digest
Events

3. Community Submissions
Are Welcome
bill@nordicapis.com

4. 5 Major API Design Trends

5. Developer Experience
● Context
● Bare Minimum
● Extra Tweaks
● Shining Examples

6. DX: Context
● Huge business driver
● Part of platform strategy
● Internal/Partner/Public can
all benefit

7. DX: Bare Minimum
Authentication Scheme
HTTP Call Types
Endpoint
URI Structures,
Methods, and Paramete
Basic things you need to consume a web API

8. DX: Getting Better
Getting
Started
Guide
Human Readable
Method
Descriptions
Testing
Environment
Sample Requests and
Examples
Caters better to self-service models

9. DX: Extra Tweaks
Instant Load
Rate this Page
Dark Mode
Status
Widget
Featured
Topics
Click to
Copy
Searchability
Impressive additions to increase efficiency

10. DX: Shining Examples
TwilioStripe
Github Shopify

11. - Adeel Ali, CEO of APIMatic,
Speaking @ Nordic APIs Platform Summit, 2018
DX: Remove Redundancy
“The golden principle of
developer experience – remove
the redundancy from the life of
developers”

12. GraphQL
● Context
● Benefits
● 4 Examples in the Wild
● Tooling

13. GraphQL: Context
A valid descriptor within GraphQL:
A simple request:
A simple result:
● Application
query
language
● Facebook
origin
● Unifies
request and
data retrieval
process

14. GraphQL: Benefits
Simplicity : More elegant data retrieval
Efficiency: Packaging data into single request
Stability : Single point of entry, community support
Low Overhead : GraphQL is a specification = compatibility
Learnability : improves understanding and organization

15. AWS AppSync
One GraphQL example in practice
GraphQL used to interact with app data
"AWS AppSync is an enterprise level, fully managed GraphQL service with
real-time data synchronization and offline programming features."

16. GraphQL at AirBnb
Supporting "Backend-Driven UI" at Airbnb
Interactive GraphQL IDE from
"Airbnb is moving 10x faster at scale with GraphQL and Apollo" - Adam Neary,
AirBnB

17. GraphQL at Twitter
Aiding the microservices model
Used for subscriptions at
"Clients subscribe to an event with a GraphQL query and receive payloads" -
Laney Kuenzel
SOURCE: https://about.sourcegraph.com/graphql/graphql-at-twitter

18. GraphQL at Walmart
Data retrieval using open source library
Lacinia by
"We’ve been using GraphQL in production for over a year for multiple services." -
Brandon Carrell, Software Engineer, eReceipts @WalmartLabs

19. GraphQL: Tooling
GraphiQL
Voyager
graphdoc
GraphQL schema documentation
Explore as interactive graph
in-browser IDE for exploring
GraphQL

20. - Lee Byron, GraphQL Co-Creator
Interviewed by Nordic APIs, Fall 2018
On GraphQL Growth
“there’s a ton of large companies
that are using GraphQL and that’s
only three years out from
open-sourcing. I think that’s pretty
incredible but there’s always room
to grow”

21. OpenAPI Specification
● Context
● Use Cases
● Community
● Sample Code
● Tooling

22. A specification for creating
machine-readable interface files
for describing, producing,
consuming, and visualizing web
services in a RESTful
architecture.
OpenAPI: Context
What Is It?

23. OpenAPI: Use Cases
What Is It Good For?
Documentation : Generate descriptive docs
Gen: Auto generate libraries & SDKs
Design-First : A more modern, standard API dev process
Testing : Declarative resource specification enables better
testing/exploration/sandboxing.
Benefits : Speed, security, auto-generation

24. OpenAPI: Community
From Swagger to Linux Foundation
● 2016: Linux
Foundation
● 30+ members
● v3.0.2
● 2011, Tony Tam
● Smartbear
● Wordnik

25. OpenAPI: Sample Code
Both written in YAML

26. OpenAPI: Tooling
Many open source generators, validators, linters, etc.
SwaggerUI
ReDoc
Swagger Codegen
API client libraries (SDK generation),
server stubs and documentation
Open source doc generator alternative w/ many benefits
A widely used API documentation
generator

27. Why Adopt OpenAPI Spec?
"The OpenAPI specification can be
used to accelerate and secure API
creation and evolution."
-Arnaud Lauret, The API Handyman
Nordic APIs Platform Summit 2018

28. AsyncAPI
● Context
● Protocols
● Community
● Benefits/Drawbacks
● Sample Code
● Tooling

29. Event-Driven Architecture
ASYNCHRONOUS
MESSAGE-BASED
STREAMING
AUTOMATED
=ALT. PROTOCOLS
WEBSOCKETS
WEBHOOKS
CALLBACKS
REST HOOKS
POLLING
PUB-SUB
Some argue REST doesn't meet these new styles

30. AsyncAPI: Context
A specification for
documenting
event-driven APIs
Because event-driven APIs need love too!

31. AsyncAPI: Protocols
Protocols good for documenting with AsyncAPI. *under consideration
AMQP
MQTT
WebSocket
Kafka
CoAP*
Others Include:
HTTP
JMS
STOMP
NATS*
Google Cloud
Pub/Sub*

32. AsyncAPI: Community
● Fran Méndez, Project Director
● Origin: Hitch, API Changelog
● AsyncAPI Initiative

33. AsyncAPI: Sample Code
Info Object Define Servers
Events Object - holds send and receive operations

34. AsyncAPI: Benefits
Protocol Agnostic: Custom header definitions in messages
Open Source : Community inspection, industry growth
Machine Readable : Creates definitions machines can read
Human Readable : Use to generate docs, sandboxes, etc.
Use Cases : Asynchronous, message-driven, DevOps,
microservices, SaaS, IoT, & more.

35. AsyncAPI: Tooling
Playground
Validator
AsyncAPI Generator
Creates AsyncAPI spec from Go
message structures
Supports AsyncAPI
generate documentation in multiple
formats
https://playground.asyncapi.io/
Markdown documentation, Node.js
code, HTML documentation
AsyncAPI Generator

36. What Others Think
"Microservices underline the
need for event-based
communication in distributed
architectures. AsyncAPI brings the
richness of the REST API ecosystem to
asynchronous APIs
-Matt McClarty, MuleSoft

37. OAuth + OpenID Connect
● Open Standard
● Security Context
● Scopes
● Benefits
● Implementation
Options

38. Security = Paramount
Holistic Platform Perspective
APIs
GDPR
IoT
Mobile Apps
Website, Desktop

39. OAuth: Context
● Industry-standard
● Most web APIs adopt
OAuth is an open standard for
delegation and authorization
on the internet

40. OpenID Connect: Context
● Verify identity
● Gather user information
● REST-like
An identity-centric
authentication protocol that
builds on the OAuth standard

41. OAuth Flows and Powers
1. Authorization Code Grant
2. Implicit Flow
3. Client Credentials Flow
4. Resource Owner Password
Credentials Flow
5. Dynamic Client Registration
6. Assisted Token Flow
7. Introspection
8. Revocation
https://nordicapis.com/8-types-of-oauth-flows-and-powers/

42. Example: Implicit Flow
● Browser based

43. OAuth + OpenID Connect
"OAuth (and more recently
OpenID Connect) is the golden
standard for giving clients
secure access to a user’s data
in a transparent and controlled
fashion."
-Thomas Bush, Nordic APIs Blog

44. There's The 5 Design Trends!
But what's happening outside of API design?

45. New API Sectors in 2019
● Retail
● eCommerce
● MarTech
● Banking
● DevOps
● AI
● Business
● others...

46. Don't Adopt Trends on Face Value
"Boring is best."
-Martin Buhr,
Nordic APIs Platform Summit 2018

47. Some Practical API Design Tips
1. Understand The REST Standard
2. Use the Right HTTP Method
3. Know How to Define Resources
4. Use Sub-resources
5. Do not Use Java Method Name Patterns
6. If You Do Version Your REST Service, Do So Consistently
7. JSON Over XML For Most Cases
8. Return the Right Status Code
-Adriano Moto, Ford
Writing on The Nordic APIs Blog

48. BILL
DOERRFELD
@DoerrfeldBill
Austin API
Summit 2019
A Snapshot of API Design
Trends In 2019
THANK YOU

49. slideshare.net/BillConradDoerrfeld
Slides are up:

50. Subscribe:
https://nordicapis.com/newsletter/

51. Share Your API Story
Articles, LiveCasts, Platform Summit 2019

52. CONTACT
bill@nordicapis.com
@DoerrfeldBill

53. BILL
DOERRFELD
@DoerrfeldBill
Austin API
Summit 2019
A Snapshot of API Design
Trends In 2019