have emerged that just offer APIs as their product ▸ APIs as Product market worth $6.27B, growing 40% ▸ APIs were 83% of global web traf fi c in 2018 ▸ API Management Tools will hit $5.1B in 2023, at a 33% CAGR 2 Bessemer Venture Partners, State of the Cloud 2020
IT IMPORTANT? ▸ Programmatic Interface to a set of functionality or data ▸ Application development becomes easier, faster by consuming building blocks ▸ You no longer have to be an expert in a domain to get value from it (e.g payments, phone/SMS, email, authentication, shipping, AI) 3 The World Through an API, Martin Casado, a16z
Started with app to app integrations, for data exchange & automation 2. Development of lightweight, easy to use APIs → wide adoption 3. Expanded with mobile apps that need to sync or fetch data 4. Skyrocketing due to demand for platforms and developer ecosystems 5. Emerging Digital Transformation of incumbent organizations 5 The State of API 2020 Report, SmartBear
an existing business by leveraging technology, people & processes ▸ Enables new business models, new partnerships or a coordinated response to market and regulatory needs ▸ APIs are a catalyst, used to break down data silos and surface information that was previously locked up in legacy data stores ▸ Precipitated by users expecting a customer experience on par with modern consumer mobile apps ▸ Makes it easy to surface many, customized experiences, e.g. web, mobile, kiosks etc. 6 3 Companies doing it right:
APIs: used only inside an organization - the vast majority ▸ Partner APIs: used by selected partners, by invitation ▸ Ecosystem APIs: used by anyone outside the organization (tip of the iceberg) 7 2020 State of the API Report, Postman
c Languages that can be used to describe an API’s behavior ▸ Human readable/writable and machine- readable ▸ Once you have an API de fi nition, you can use tooling to render documentation or even generate tests and clients ▸ Examples: Swagger → OpenAPI, RAML, AsyncAPI, Proto3, API Blueprint 11 API De fi nition Document API Documentation API Tests
so much more than just a Spec: it’s the place where thinking and collaboration around APIs happens, whether it’s about the original OpenAPI description format, or adjacent specs such as JSON Schema and AsyncAPI, and beyond. ▸ We think OAI is becoming a focal point where the requirements of API builders and API consumers are converging! 13
makes a good API since Joshua Bloch’s How to Design a Good API and Why it Matters 1. Easy to learn 2. Easy to use, even without documentation 3. Hard to misuse 4. Easy to read and maintain code that uses it 5. Suf fi ciently powerful to satisfy requirements 6. Easy to extend 7. Appropriate to audience ▸ API Design brings intent into the process by authoring an API De fi nition Document, created from scratch and not generated from existing code - like a wireframe for UI 15 API De fi nition Document - User Needs - Vocabulary - Data Structures - Validations - Resources - Actions - Error Cases - Styles & Standards
APIs became more important, the industry realized we need to treat them as products ▸ Emergence of the API Product Manager, designing an API Product such that it meets the needs of Developers and their customers’ use cases ▸ Iterate and get feedback from future API Consumers ▸ API De fi nition Document becomes “contract” once agreed 16 API De fi nition Document { } Mock Prototype Feedback API Documentation API Tests
the API before any other layers of you application, such as the UI ▸ Jeff Bezos famously mandated all teams to use service interfaces which are designed to be externalizable ▸ Start with the API and combine endpoints into different user experiences, as needs of the market evolve ▸ A great place to start when you don’t know where you’ll end up but it might mean you risk delivering an API developers won’t use ▸ May lead to creating numerous versions of the API that you’ll have to support 17
keep things consistent in a small team that works on few APIs ▸ Once APIs proliferate across a large organization with multiple teams, inconsistencies creep in ▸ An inconsistent API is hard to learn and understand and dif fi cult to maintain ▸ Organizations develop API Style Guides and Security Guidelines, but it’s dif fi cult to enforce them without tooling and processes ▸ A robust API publishing process is needed to maintain quality, security and control 19 Screenshot from Stoplight Spectral, showing warnings when scanning an API De fi nition
best practices as you would with any application ▸ Keep in mind the OWASP API Top-10 ▸ Authenticate via proven standards: Basic Auth, OAuth 2.0 and use HTTPS ▸ Don't leak information in errors or IDs ▸ Protect behind an API Gateway and Rate limit! ▸ Monitor your services 20 A Design-First Approach for API Security, Keynote at API Days San Francisco, 2018
Web APIs: Generally REST-ish APIs are by far the most commonly used ▸ Query APIs: GraphQL, when querying is important but use cases are not known ▸ Publish-Subscribe APIs: Kafka for event- driven, streaming APIs ▸ RPC APIs: SOAP (don’t), gRPC for ef fi ciency, internal-only apps ▸ Flat File Transfer: Large, batch-type operations 21 For a detailed discussion on which styles to use and when, see Z’s excellent presentation “What API, Your Guide to API Styles”
the APIs used today are HTTP/JSON “RESTful” APIs ▸ Fully REST-compliant APIs are rare in the wild and should satisfy 6 architectural constraints. ▸ Easy to consume, with existing tooling, lots of familiarity because they are web APIs 22 Common API Search terms, Google Trends
“Plain Old XML”, RPC-style APIs ▸ Level 1: Use Resources (nouns), not a single endpoint ▸ Level 2: Use different HTTP methods (verbs) such as GET or POST [Aim for at least this level] ▸ Level 3: “Hypertext As The Engine Of Application State”, linked elements [Precondition for true REST] 23 Leonard Richardson’s API Maturity Model
plural for resources, e.g. /orders not /order ▸ A resource without an ID represents a collection, e.g. /customers vs /customers/123 ▸ Resources can be nested to denote relationship, e.g. customers/123/orders (but don’t overdo it) 24 ▸ GET to retrieve data, no request body. May return a single object or a collection ▸ POST to create a new item, send representation in request body. Response will contain the created item representation ▸ PUT to modify an item, send the new representation in the request body. Response contains the modi fi ed representation ▸ DELETE to remove an item, no request or response body ▸ 200 OK ▸ 201 Created ▸ 202 Accepted ▸ 204 No Content ▸ 400 Bad Request ▸ 401 Unauthorized ▸ 403 Forbidden ▸ 404 Not Found Naming Resources Method Usage Status Codes
▸ Use of link relations allows consuming application to discover resources ▸ Allows underlying object to change (authors, categories) ▸ Easy to maintain and modify 25 RESTful JSON design pattern makes it easy to add links in JSON payloads
safety and querying built-in ▸ Great when the use cases are not known upfront, i.e. random querying patterns ▸ JavaScript on frontend ▸ GraphQL schema ▸ Wide adoption: Facebook, GitHub, Intuit, Audi, Shopify, Atlassian… 27 GraphQL.org
BUILD AND MAINTAIN APIS ▸ Ideation: Collect requirements, data model, vocabulary, goals [Product Manager] ▸ Design: Iterate on de fi nition with API Consumers via Mock [Architect/Product Manager] ▸ Development: Implement design against contract and functional requirements [Developer] ▸ Con fi guration: Prepare and set up for deployment [Developer] 29 Domain Data Style Guide & Vocabulary API Description Document Collections & Scenarios Runtime Configuration Developer Portal API Gateway Environment Sandbox API Consumer
via CI/ CD to correct environment, run tests [DevOps] ▸ Publishing: Make API available on Gateway and Dev Portal [DevOps] ▸ Operation: Monitor health and ensure uptime/security [DevOps] ▸ Analyze: Review metrics and user feedback - iterate to Ideation phase [Product Manager] 30 Domain Data Style Guide & Vocabulary API Description Document Collections & Scenarios Runtime Configuration Developer Portal API Gateway Environment Sandbox API Consumer
API Consumers authenticate, discover and learn the API [DevRel] ▸ API Gateway: Authenticates, protects and meters API calls sent by API Consumer [DevOps] ▸ Deployment Environments: Production, Regional or Test - service API Calls sent by API Consumer [DevOps] ▸ Sandbox: Simpli fi ed environment where API Consumer can play with API [DevOps] 31 Domain Data Style Guide & Vocabulary API Description Document Collections & Scenarios Runtime Configuration Developer Portal API Gateway Environment Sandbox API Consumer
in APIs :) ▸ The consensus is to try to prolong and avoid it as much as possible but doing good market research, making your API evolvable and introducing only non- breaking changes ▸ Eventually you’ll have to make breaking changes and then you’ll have to evaluate different ways to indicate API versions 33 If you MUST version: URL /api/v2/… Changes all the resources Header Stripe-Version: 2017-05-25 Not Intuitive Content Type Accept: mymediatype.v2+json Not Intuitive API Versioning: a case of picking your poison
known as “API Strategy Team” or “API Council” ▸ Responsible for API Standards, Tools and Processes ▸ Approves API Designs and Publishes Services ▸ Can become a bottleneck so try to decentralize approvals and give teams the know-how and automation to serve themselves ▸ Exec sponsorship is key to success ▸ Team members: API Architects, SMEs, DevRel 34
PROVIDER ▸ A user must pass through all the gates & all the stages of the funnel ▸ Has an app whose usage is continuously increasing ▸ High Retention, Low Churn, NRR, measure with tools like Moesif 37 DISCOVER LEARN SUCCEED RETAIN
LEARN SUCCEED RETAIN Content, Messaging, SEO DevRel Landing Page per Use Case & Persona Check out Adam DuVander’s book: Developer Marketing Does Not Exist
LEARN SUCCEED RETAIN Make it Easy to Make that 1st API Call (1-2-3) Tutorials, Sample Code, SDKs (but keep them fresh) Interactive “Try It” Easy to Get Credentials Use Playgrounds like Postman or CodeSandbox
LOOK LIKE AND WHY IT MATTERS ▸ Combine a great, consistent API design, with one that is reliably available ▸ Be careful about versioning APIs; plan ahead and don’t make breaking changes ▸ Easy to start: Time To First Hello World in a Sandbox (Authentication is always tricky) ▸ Have a great Developer Portal where it’s easy to fi nd: - Quickstart Guide - Interactive Reference Documentation - Tutorials - Code Examples - SDKs ▸ Provide easy ways to give feedback and get support ▸ All this means that Developers are likely to try your API and will create apps that use it 42 Stripe has one of the best API Developer Portals, really makes it easy to fi nd information and ticks all the boxes Navigation Pane Example Response Textual Description
monetized indirectly: they are Product-led and support the main product by providing integrations which tend to be persistent or by enabling lucrative partnerships (e.g. GitHub) ▸ Ecosystem APIs enable developers to build apps that reinforce a platform or marketplace, also indirect monetization (e.g. Atlassian) ▸ Steady rise of APIs as a Product (See slide on API Economy) ▸ Transactional & tiered pricing (Twilio) ▸ Fixed pricing (SendGrid) 43
Experience: ▸ Nylas API for breadth of functionality ▸ Stripe for the API Reference, tutorials and sample apps ▸ Twilio for the general documentation format ▸ GitHub for the excellent intros ▸ Dropbox for the API Explorer but not much else ▸ Spotify for overall organization and navigation 48
paraskakis
recruitengineers
re_taro
koichiotomo
syntasso
shimastripe
oracle4engineer
techiro
16bitidol
tubone24
ryosukeigarashi
emiki
palkan
sonatard
chriscoyier
maggiecrowley
sachag
brianwarren
tammyeverts
keavy
smashingmag
ammeep
vanstee
geoffreycrofte
