EMMANUEL PARASKAKIS API BEST PRACTICES 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 

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 

APIS & DEVELOPER EXPERIENCE API EXAMPLE 4 Request Response 

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 

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: 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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” 

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 

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 

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 

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 

APIS & DEVELOPER EXPERIENCE REAL WORLD API - GITHUB 26 Request Response Resource pluralization POST to collection 201 Status Hypermedia URLs 

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 

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 

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 

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 

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 

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 

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 

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 

APIS & DEVELOPER EXPERIENCE FEDERATED PLATFORM TEAM 35 

APIS & DEVELOPER EXPERIENCE DEVELOPER EXPERIENCE ENGAGEMENT 36 DISCOVER LEARN SUCCEED RETAIN Understand What 
 I can Achieve TTFHW App 
 Published Usage & 
 Retention STAGES GATES 

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 

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 

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 

APIS & DEVELOPER EXPERIENCE SUCCESS OBJECTIVE: PUBLISH APP 40 DISCOVER LEARN SUCCEED RETAIN Easy to Get Support Friendly Pricing Great Reference Docs Video Walkthroughs 

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 

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 

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 

APIS & DEVELOPER EXPERIENCE NEWSLETTERS & BLOGS ▸ Nordic APIs ▸ API Evangelist ▸ Launchany Newsletter ▸ Net API Notes Newsletter ▸ GraphQL Weekly Newsletter ▸ The API Changelog Newsletter 44 

APIS & DEVELOPER EXPERIENCE API PM RESOURCES ‣ Adidas API PO Training ‣ Get in the Van - Michael Sippey ‣ The World Through an API - A16Z 45 

APIS & DEVELOPER EXPERIENCE BOOKS 46 

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 

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