Share
Embed
Transcript
48 slides
-
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 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 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 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