Specification-driven API Design vs Technical Writers

•

1 recomendación•722 vistas

This talk, originally given at tcworld18, shows the importance of API Design and documentation for developer experience (DX), introduces OpenAPI and then explains how a spec-driven API lifecycle can help with DX, highlighting the role of technical writers.

Software

Specification-driven API Design
vs.
Technical Writers
Lukas Rosenstock
tcworld18, 15th Nov 2018

APIs?
DX
Developer
Experience
Open
API
Spec-
driven
Tech
Writers

“Docs
Like
Code”

APIs?
DX
Developer
Experience
Open
API
Spec-
driven
Tech
Writers
API
abbr. Application
Programming Interface n.
A remote interface available
over HTTP(S), designed in a
REST or RPC style.
“Docs
Like
Code”

APIs?
DX
Developer
Experience
Open
API
Spec-
driven
Tech
Writers
Public
Partner
Private
Microservices
“Docs
Like
Code”

APIs?
DX
Developer
Experience
Open
API
Spec-
driven
Tech
Writers
“Docs
Like
Code”
Public
Partner
Private
Microservices

APIs?
DX
Developer
Experience
Open
API
Spec-
driven
Tech
Writers
API
Design
Scope
Consistency
Future-proof
“Docs
Like
Code”

APIs?
DX
Developer
Experience
Open
API
Spec-
driven
Tech
Writers
API
Design
Docs
Conceptual
Guides / Samples
API Reference
“Docs
Like
Code”

APIs?
DX
Developer
Experience
Open
API
Spec-
driven
Tech
Writers
Spec
machine-
readable
“Docs
Like
Code”

Metadata
openapi: 3.0.0
info:
title: ipify
version: v1
description: A Simple IP Address API
servers:
- url: 'https://api.ipify.org/'

Paths
paths:
/:
get:
summary: Get client IP
parameters:
- in: query
name: format
description: 'The format to return the response in, i.e. json.'
schema:
type: string
default: json
responses:

Responses / JSON Schemas
responses:
'200':
description: Success response
content:
application/json:
schema:
type: object
properties:
ip:
type: string
example: 88.68.10.107

APIs?
DX
Developer
Experience
Open
API
Spec-
driven
Tech
Writers
Spec
machine-
readable
Docs
Reference

Manual
Writing
Auto-
Generation
Code
Implementation
“Docs
Like
Code”

APIs?
DX
Developer
Experience
Open
API
Spec-
driven
Tech
Writers
API
Design
“Docs
Like
Code”

APIs?
DX
Developer
Experience
Open
API
Spec-
driven
Tech
Writers
Spec
machine-
readable
Manual
Writing
Visual
Tools
API
Design
“Docs
Like
Code”

APIs?
DX
Developer
Experience
Open
API
Spec-
driven
Tech
Writers
Spec
machine-
readable
Manual
Writing
Visual
Tools
API
Design
Docs
Reference

“Docs
Like
Code”

APIs?
DX
Developer
Experience
Open
API
Spec-
driven
Tech
Writers
Spec
machine-
readable
Manual
Writing
Visual
Tools
API
Design
Docs
Reference

Code
Client SDKs
Server Stubs
Mock Servers“Docs
Like
Code”

APIs?
DX
Developer
Experience
Open
API
Spec-
driven
Tech
Writers
API
Design
Docs
Conceptual
Guides / Samples
API Reference
Review
“The Good Stuff”
“Docs
Like
Code”

APIs?
DX
Developer
Experience
Open
API
Spec-
driven
Tech
Writers
Not jobless!
More technical
“Docs
Like
Code”

APIs?
DX
Developer
Experience
Open
API
Spec-
driven
Tech
Writers
“Docs
Like
Code”
Use developer toolchain
for writing
Markdown

Más contenido relacionado

La actualidad más candente

APIDays - API Design WorkshopRestlet

apidays LIVE New York 2021 - Designing API's: Less Data is More! by Damir Svr...apidays

[API World 2021 ] - Understanding Cloud Native DeploymentWSO2

apidays LIVE Australia - Federating API Development at Australia’s largest bu...apidays

apidays LIVE Hong Kong 2021 - Multi-Protocol APIs at Scale in Adidas by Jesus...apidays

OpenAPI Spec at Google (Open API Initiative Meetup on 2016-09-15)Open API Initiative (OAI)

Designing APIs with OpenAPI SpecAdam Paxton

apidays LIVE London 2021 - Consumer-first APIs in Open Banking by Chris Dudle...apidays

Tools and techniques for APIsJason Harmon

apidays LIVE Australia - API Design in Fintech: Challenges and Opportunities ...apidays

Building APIs with the OpenApi SpecPedro J. Molina

Bulletproofing Your APIs: Why Users’ Feedback MattersPronovix

apidays LIVE London 2021 - Designing APIs: Less Data is More by Damir Svrtan,...apidays

Proliferating OpenAPI at GoogleOpen API Initiative (OAI)

APIdays Paris 2014 - The State of Web API LanguagesRestlet

{Re}designing a Developer PortalPronovix

Essential Ingredients for a Successful API ProgramJason Harmon

apidays LIVE Hong Kong 2021 - Better API DX with a CLI by Phil Nash, Twilioapidays

apidays LIVE Australia 2021 - From apps to APIs: how no-code is transforming ...apidays

9 Months and Counting with Jeff Borek of IBM OpenAPI Meetup 2016 09 15Open API Initiative (OAI)

La actualidad más candente (20)

APIDays - API Design Workshop

apidays LIVE New York 2021 - Designing API's: Less Data is More! by Damir Svr...

[API World 2021 ] - Understanding Cloud Native Deployment

apidays LIVE Australia - Federating API Development at Australia’s largest bu...

apidays LIVE Hong Kong 2021 - Multi-Protocol APIs at Scale in Adidas by Jesus...

OpenAPI Spec at Google (Open API Initiative Meetup on 2016-09-15)

Designing APIs with OpenAPI Spec

apidays LIVE London 2021 - Consumer-first APIs in Open Banking by Chris Dudle...

Tools and techniques for APIs

apidays LIVE Australia - API Design in Fintech: Challenges and Opportunities ...

Building APIs with the OpenApi Spec

Bulletproofing Your APIs: Why Users’ Feedback Matters

apidays LIVE London 2021 - Designing APIs: Less Data is More by Damir Svrtan,...

Proliferating OpenAPI at Google

APIdays Paris 2014 - The State of Web API Languages

{Re}designing a Developer Portal

Essential Ingredients for a Successful API Program

apidays LIVE Hong Kong 2021 - Better API DX with a CLI by Phil Nash, Twilio

apidays LIVE Australia 2021 - From apps to APIs: how no-code is transforming ...

9 Months and Counting with Jeff Borek of IBM OpenAPI Meetup 2016 09 15

Similar a Specification-driven API Design vs Technical Writers

Apidays Paris 2023 - API design first: A case for a better language, Emmanu...apidays

API workshop: Introduction to APIs (TC Camp)Tom Johnson

Raml api designerD.Rajesh Kumar

REST Coder: Auto Generating Client Stubs and Documentation for REST APIsHiranya Jayathilaka

2022 APIsecure_Securing APIs with Open StandardsAPIsecure_ Official

APIs at Scale with TypeSpec by Mandy Whaley, MicrosoftNordic APIs

GraphQL: Enabling a new generation of API developer toolsSashko Stubailo

Make Your API Catalog Essential with z/OS Connect EETeodoro Cipresso

GraphQL: The Missing Link Between Frontend and Backend DevsSashko Stubailo

Building Beautiful REST APIs with ASP.NET CoreStormpath

Survival Strategies for API Documentation: Presentation to Southwestern Ontar...Tom Johnson

API workshop by AWS and 3scale3scale

Will the Real Public API Please Stand Up? Amir ZukerCodeValue

Public APIAmir Zuker

APIdays 2015 - The State of Web API LanguagesJerome Louvel

APIdays 2015 - The State of Web API LanguagesRestlet

Content Strategy and Developer Engagement for DevPortalsAxway

Open API (aka Swagger) - DDD by Night May 2020Pratik Khasnabis

API Conference 2021José Haro Peralta

API Documentation presentation to East Bay STC ChapterTom Johnson

Similar a Specification-driven API Design vs Technical Writers (20)

Apidays Paris 2023 - API design first: A case for a better language, Emmanu...

API workshop: Introduction to APIs (TC Camp)

Raml api designer

REST Coder: Auto Generating Client Stubs and Documentation for REST APIs

2022 APIsecure_Securing APIs with Open Standards

APIs at Scale with TypeSpec by Mandy Whaley, Microsoft

GraphQL: Enabling a new generation of API developer tools

Make Your API Catalog Essential with z/OS Connect EE

GraphQL: The Missing Link Between Frontend and Backend Devs

Building Beautiful REST APIs with ASP.NET Core

Survival Strategies for API Documentation: Presentation to Southwestern Ontar...

API workshop by AWS and 3scale

Will the Real Public API Please Stand Up? Amir Zuker

Public API

APIdays 2015 - The State of Web API Languages

Content Strategy and Developer Engagement for DevPortals

Open API (aka Swagger) - DDD by Night May 2020

API Conference 2021

API Documentation presentation to East Bay STC Chapter

Más de Lukas Leander Rosenstock

Hybride Entwicklung mit IonicLukas Leander Rosenstock

Das IndieWeb - mach mit!Lukas Leander Rosenstock

App.net IntroductionLukas Leander Rosenstock

PHP Frameworks, Libraries & Tools - BarCamp RheinMain 2013Lukas Leander Rosenstock

OpenID for starters - Barcamp Berlin IILukas Leander Rosenstock

OpenID für Anfänger - MRMCDLukas Leander Rosenstock

Más de Lukas Leander Rosenstock (6)

Hybride Entwicklung mit Ionic

Das IndieWeb - mach mit!

App.net Introduction

PHP Frameworks, Libraries & Tools - BarCamp RheinMain 2013

OpenID for starters - Barcamp Berlin II

OpenID für Anfänger - MRMCD

Último

Project Based Learning (A.I).pptx detail explanationkaushalgiri8080

How To Use Server-Side Rendering with Nuxt.jsAndolasoft Inc

why an Opensea Clone Script might be your perfect match.pdfjoe51371421

Optimizing AI for immediate response in Smart CCTVshikhaohhpro

Hand gesture recognition PROJECT PPT.pptxbodapatigopi8531

Der Spagat zwischen BIAS und FAIRNESS (2024)OPEN KNOWLEDGE GmbH

Cloud Management Software Platforms: OpenStackVICTOR MAESTRE RAMIREZ

Test Automation Strategy for Frontend and BackendArshad QA

Diamond Application Development Crafting Solutions with PrecisionSolGuruz

Adobe Marketo Engage Deep Dives: Using Webhooks to Transfer DataBradBedford3

(Genuine) Escort Service Lucknow | Starting ₹,5K To @25k with A/C 🧑🏽‍❤️‍🧑🏻 89...gurkirankumar98700

Tech Tuesday-Harness the Power of Effective Resource Planning with OnePlan’s ...OnePlan Solutions

SyndBuddy AI 2k Review 2024: Revolutionizing Content Syndication with AIABDERRAOUF MEHENNI

Unveiling the Tech Salsa of LAMs with Janus in Real-Time ApplicationsAlberto González Trastoy

CALL ON ➥8923113531 🔝Call Girls Kakori Lucknow best sexual service Online ☂️anilsa9823

What is Binary Language? Computer Number SystemsJheuzeDellosa

TECUNIQUE: Success Stories: IT Service providermohitmore19

The Essentials of Digital Experience Monitoring_ A Comprehensive Guide.pdfkalichargn70th171

Unlocking the Future of AI Agents with Large Language Modelsaagamshah0812

A Secure and Reliable Document Management System is Essential.docxComplianceQuest1

Specification-driven API Design vs Technical Writers

1. Specification-driven API Design vs. Technical Writers Lukas Rosenstock tcworld18, 15th Nov 2018

2. APIs? DX Developer Experience Open API Spec- driven Tech Writers  “Docs Like Code”

3. APIs? DX Developer Experience Open API Spec- driven Tech Writers API abbr. Application Programming Interface n. A remote interface available over HTTP(S), designed in a REST or RPC style. “Docs Like Code”

4. APIs? DX Developer Experience Open API Spec- driven Tech Writers Public Partner Private Microservices “Docs Like Code”

5. APIs? DX Developer Experience Open API Spec- driven Tech Writers “Docs Like Code” Public Partner Private Microservices

6. APIs? DX Developer Experience Open API Spec- driven Tech Writers API Design Scope Consistency Future-proof “Docs Like Code”

7. APIs? DX Developer Experience Open API Spec- driven Tech Writers API Design Docs Conceptual Guides / Samples API Reference “Docs Like Code”

8. APIs? DX Developer Experience Open API Spec- driven Tech Writers Spec machine- readable “Docs Like Code”

10. Metadata openapi: 3.0.0 info: title: ipify version: v1 description: A Simple IP Address API servers: - url: 'https://api.ipify.org/'

11. Paths paths: /: get: summary: Get client IP parameters: - in: query name: format description: 'The format to return the response in, i.e. json.' schema: type: string default: json responses:

12. Responses / JSON Schemas responses: '200': description: Success response content: application/json: schema: type: object properties: ip: type: string example: 88.68.10.107

13. APIs? DX Developer Experience Open API Spec- driven Tech Writers Spec machine- readable Docs Reference  Manual Writing Auto- Generation Code Implementation “Docs Like Code”

14. ReDoc

15. Swagger UI

16. APIs? DX Developer Experience Open API Spec- driven Tech Writers “Docs Like Code”

17. APIs? DX Developer Experience Open API Spec- driven Tech Writers API Design “Docs Like Code”

18.

19. APIs? DX Developer Experience Open API Spec- driven Tech Writers Spec machine- readable Manual Writing Visual Tools API Design “Docs Like Code”

20. stoplight.io

21. APIs? DX Developer Experience Open API Spec- driven Tech Writers Spec machine- readable Manual Writing Visual Tools API Design Docs Reference  “Docs Like Code”

22. APIs? DX Developer Experience Open API Spec- driven Tech Writers Spec machine- readable Manual Writing Visual Tools API Design Docs Reference  Code Client SDKs Server Stubs Mock Servers“Docs Like Code”

23. APIs? DX Developer Experience Open API Spec- driven Tech Writers Spec machine- readable Manual Writing Visual Tools API Design Docs Reference  Code Code = Spec ? Tests “Docs Like Code”

24. APIs? DX Developer Experience Open API Spec- driven Tech Writers Spec machine- readable Manual Writing Visual Tools API Design Docs Reference  Code Tests Single Source Of Truth “Docs Like Code”