Upgrade to Pro — share decks privately, control downloads, hide ads and more …

API Best Practices

paraskakis
September 06, 2022

API Best Practices

Slides from my "How to API" intro session

paraskakis

September 06, 2022
Tweet

More Decks by paraskakis

Other Decks in Technology

Transcript

  1. APIS & DEVELOPER EXPERIENCE THE API ECONOMY ▸ Entire companies

    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
  2. APIS & DEVELOPER EXPERIENCE WHAT’S AN API AND WHY IS

    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
  3. APIS & DEVELOPER EXPERIENCE WHAT’S DRIVING THE API ECONOMY 1.

    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
  4. APIS & DEVELOPER EXPERIENCE DIGITAL TRANSFORMATION ▸ Radical rethinking of

    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:
  5. APIS & DEVELOPER EXPERIENCE THE AUDIENCE FOR APIS ▸ Internal

    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
  6. APIS & DEVELOPER EXPERIENCE HOW WE BUILT APIS & SERVICES

    8 API as a by-product of building apps API documentation generated from code Design- fi rst API Development API Development Consistency
  7. APIS & DEVELOPER EXPERIENCE 2006: API AS A BY-PRODUCT API

    as a by-product of building apps API documentation generated from code Design- fi rst API Development API Development Consistency 9
  8. APIS & DEVELOPER EXPERIENCE 2010: API DOCS FROM CODE 10

    API as a by-product of building apps API documentation generated from code Design- fi rst API Development API Development Consistency
  9. APIS & DEVELOPER EXPERIENCE API DEFINITION DOCUMENTS ▸ Domain-Speci fi

    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
  10. APIS & DEVELOPER EXPERIENCE OPENAPI ▸ Evolved from Swagger speci

    fi cation ▸ Most widely used API De fi nition Format ▸ Under Linux Foundation: OpenAPI Initiative ▸ 3.1 is the latest version 12
  11. APIS & DEVELOPER EXPERIENCE OPENAPI INITIATIVE ▸ OpenAPI is becoming

    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
  12. APIS & DEVELOPER EXPERIENCE 2014: DESIGN-FIRST API DEVELOPMENT 14 API

    as a by-product of building apps API documentation generated from code Design- fi rst API Development API Development Consistency
  13. APIS & DEVELOPER EXPERIENCE API DESIGN ▸ We’ve known what

    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
  14. APIS & DEVELOPER EXPERIENCE API AS A PRODUCT ▸ As

    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
  15. APIS & DEVELOPER EXPERIENCE WHY API-FIRST? ▸ API-First means designing

    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
  16. APIS & DEVELOPER EXPERIENCE 2018: CONSISTENCY ACROSS APIS 18 API

    as a by-product of building apps API documentation generated from code Design- fi rst API Development API Development Consistency
  17. APIS & DEVELOPER EXPERIENCE API GOVERNANCE ▸ It’s easy to

    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
  18. APIS & DEVELOPER EXPERIENCE API SECURITY ▸ Use common security

    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
  19. APIS & DEVELOPER EXPERIENCE A TAXONOMY OF API STYLES ▸

    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”
  20. APIS & DEVELOPER EXPERIENCE RISE OF REST ▸ Most of

    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
  21. APIS & DEVELOPER EXPERIENCE REST API MATURITY ▸ Level 0:

    “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
  22. APIS & DEVELOPER EXPERIENCE COMMON LEVEL 2 CONVENTIONS ▸ Use

    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
  23. APIS & DEVELOPER EXPERIENCE EXAMPLE OF AN EVOLVABLE REST API

    ▸ 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
  24. APIS & DEVELOPER EXPERIENCE REAL WORLD API - GITHUB 26

    Request Response Resource pluralization POST to collection 201 Status Hypermedia URLs
  25. APIS & DEVELOPER EXPERIENCE GRAPHQL ▸ HTTP API with type

    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
  26. APIS & DEVELOPER EXPERIENCE EVENT-DRIVEN APIS ▸ Trigger is an

    Event, not request/response ▸ Publish/Subscribe ▸ Streaming Data ▸ AsyncAPI is the description format (based on OpenAPI) - adoption at Adidas, Salesforce, Slack, SAP 28 Protocol support: 
 - AMQP 
 - HTTP 
 - JMS 
 - Kafka 
 - MQTT 
 - STOMP 
 - WebSocket
  27. APIS & DEVELOPER EXPERIENCE THE API LIFECYCLE - HOW TO

    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
  28. APIS & DEVELOPER EXPERIENCE RUNTIME ENVIRONMENT ▸ Deployment: Deploy Service

    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
  29. APIS & DEVELOPER EXPERIENCE API CONSUMPTION ▸ Developer Portal: Where

    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
  30. 32 API 
 Description API 
 Standards Data 
 Models

    Security 
 Standards Repository Implementation Developer Portal Pricing Catalog Docs Analytics Runtime 
 Environment Gateway Identity API Consumer Dev Rel Tech Writer Developer PM Architect CI/CD 
 & Test CI/CD CI/CD 
 & Test
  31. APIS & DEVELOPER EXPERIENCE VERSIONING ▸ Possibly the touchiest subject

    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
  32. APIS & DEVELOPER EXPERIENCE THE API PLATFORM TEAM ▸ Also

    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
  33. APIS & DEVELOPER EXPERIENCE DEVELOPER EXPERIENCE ENGAGEMENT 36 DISCOVER LEARN

    SUCCEED RETAIN Understand What 
 I can Achieve TTFHW App 
 Published Usage & 
 Retention STAGES GATES
  34. APIS & DEVELOPER EXPERIENCE YOUR OBJECTIVE AS A SAAS API

    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
  35. APIS & DEVELOPER EXPERIENCE DISCOVERY OBJECTIVE: SIGN UP 38 DISCOVER

    LEARN SUCCEED RETAIN Content, Messaging, SEO DevRel Landing Page per Use Case & Persona Check out Adam DuVander’s book: 
 Developer Marketing Does Not Exist
  36. APIS & DEVELOPER EXPERIENCE LEARNING OBJECTIVE: SHORT TTFHW 39 DISCOVER

    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
  37. APIS & DEVELOPER EXPERIENCE SUCCESS OBJECTIVE: PUBLISH APP 40 DISCOVER

    LEARN SUCCEED RETAIN Easy to Get Support Friendly Pricing Great Reference Docs Video Walkthroughs
  38. APIS & DEVELOPER EXPERIENCE RETENTION OBJECTIVE: NRR 41 DISCOVER LEARN

    SUCCEED RETAIN Build Community Customer Success Status & 
 Dashboard Keep it Secure Evolve Sanely Check Out Orbit
  39. APIS & DEVELOPER EXPERIENCE WHAT DOES A GREAT DEVELOPER EXPERIENCE

    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
  40. APIS & DEVELOPER EXPERIENCE API MONETIZATION ▸ Most APIs are

    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
  41. APIS & DEVELOPER EXPERIENCE NEWSLETTERS & BLOGS ▸ Nordic APIs

    ▸ API Evangelist ▸ Launchany Newsletter ▸ Net API Notes Newsletter ▸ GraphQL Weekly Newsletter ▸ The API Changelog Newsletter 44
  42. APIS & DEVELOPER EXPERIENCE API PM RESOURCES ‣ Adidas API

    PO Training ‣ Get in the Van - Michael Sippey ‣ The World Through an API - A16Z 45
  43. APIS & DEVELOPER EXPERIENCE TOOLS TO CHECK OUT ▸ API

    Design ▸ Apiary ▸ SwaggerHub ▸ Stoplight ▸ API Documentation ▸ Readme ▸ Redocly ▸ Optic ▸ RapidAPI ▸ API Testing ▸ Postman ▸ Dredd ▸ API Fortress ▸ Schemathesis ▸ API Management ▸ Apigee ▸ Kong & Insomnia ▸ Solo ▸ AWS API Gateway ▸ API Analytics ▸ Moesif ▸ APIMetrics ▸ Akita ▸ GraphQL ▸ Apollo ▸ Prisma ▸ Hasura ▸ GraphiQL ▸ Security/Availability ▸ 42 Crunch ▸ Salt ▸ APISecurity ▸ APIExpert 47
  44. TEXT GREAT API EXAMPLES ▸ Adidas API for overall Developer

    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