apidays LIVE Paris 2021 - Building an Accessible API Spec with Traditional Engineering Teams by Griffin Solot-Kehl, Dolby Laboratories

•

0 gostou•243 visualizações

apidays LIVE Paris 2021 - APIs and the Future of Software December 7, 8 & 9, 2021 Building an Accessible API Spec with Traditional Engineering Teams Griffin Solot-Kehl, Developer Advocate at Dolby Laboratories

Tecnologia

Building an Accessible
API Spec with Traditional
Engineering Teams
Griffin Solot-Kehl
Developer Advocate, Dolby.io
@WingofaGriffin
1
© 2 0 2 0 D O L B Y | C O N F I D E N T I A L
© 2 0 2 1 D O L B Y

Hi, I’m Griffin
• Dolby.io
• Media enhancement and analysis APIs
• Real time communications APIs
• Developer Advocate in REST APIs >3 years
• From baby startups to big corporations
• Focus on API integrations
• Spent a LOT of time on docs pages
2
@WINGOFAGRIFFIN
© 2 0 2 1 D O L B Y

3
You need to work on
your API Spec.
© 2 0 2 1 D O L B Y
@WINGOFAGRIFFIN

Common Issues:
• Unclear/Out of Date documentation
• Hard to update existing OpenAPI Spec
• Inconsistent parameters across endpoints
• Slow process to communicate changes
• Internally
• Externally
• Less of an issue with API first development
4
@WINGOFAGRIFFIN
© 2 0 2 1 D O L B Y

5
What can we do?
© 2 0 2 1 D O L B Y
@WINGOFAGRIFFIN

Keeping a Modular Spec
• Don’t rewrite identical code
• $ref objects
• Identify patterns in new endpoints
• Use helper files
• “Global” variables to reuse
• Document what they do!
• Comment often!
swagger.io/docs/specification/using-ref/
6
@WINGOFAGRIFFIN
© 2 0 2 1 D O L B Y

Authentication
• Security vs. Simplicity
• OAuth2 Tokens
• Key Management
• Rotation tools
• Have a “validate” API endpoint
7
© 2 0 2 1 D O L B Y
@WINGOFAGRIFFIN

Keep it Simple (Stupid)
• Clear how to create, clear what the response is
• Expectations between user levels
• Label and Organize JSON well
• Encourage use of tools like jq
• Consistent Parameters
8
© 2 0 2 1 D O L B Y
@WINGOFAGRIFFIN

• Previous Employers
• Internal Docs
• Existing 3rd party APIs in stack
• Competitor Docs
Examples of Quality Docs
9
@WINGOFAGRIFFIN
© 2 0 2 1 D O L B Y

Documentation
• Verify valid OpenAPI Spec
• Readme.com, Redoc.ly, DapperDox,
WidderShins, SwaggerUI, etc.
• Ensure public facing endpoints work!
• Autogenerate Sample Code
• Make calls within website
10
@WINGOFAGRIFFIN
© 2 0 2 1 D O L B Y

Technical Debt
• Hard to change existing infrastructure
• But it will get even harder as you let it accumulate
• Turns off new users
• Existing customers will be poached
• Security vulnerabilities
11
© 2 0 2 1 D O L B Y
@WINGOFAGRIFFIN

Think Agile!
• Use Project Management techniques to get user stories
• Scrum Masters can be useful!
• As a ___ I want to ___ so I can ___
• Create goals to chuck out the technical debt
• Divide tasks into subcategories for small wins over a long period of time
12
© 2 0 2 1 D O L B Y
@WINGOFAGRIFFIN

Dogfooding!
• Make engineers use the API!
• Internal tools
• Other teams’ feedback
• Utilize the DevRel team (if applicable)
• Gather trusted user feedback
• Addition to automated testing
13
@WINGOFAGRIFFIN
© 2 0 2 1 D O L B Y

Example: Dolby.io + Box
• Enhance API used on every audio project
• Upload to Box, enhance inside
• Videos, podcasts, audio files
• Python, JS, Shell, etc. options as alternatives
• Also see Transcode, Mastering, etc.
14
@WINGOFAGRIFFIN
© 2 0 2 1 D O L B Y

Example: Dolby.io CAPI
• Communications API used for Video Calls
• Expose average user workflow
• Find common use cases
• Add “nice to have” features
• Devs get curious when quirks happen live
15
@WINGOFAGRIFFIN
© 2 0 2 1 D O L B Y

16
Everything is a
Work in Progress
© 2 0 2 1 D O L B Y
@WINGOFAGRIFFIN

17
Constant
Communication
© 2 0 2 1 D O L B Y
@WINGOFAGRIFFIN

Thank you!
@WINGOFAGRIFFIN
DOLBY.IO
18
© 2 0 2 1 D O L B Y

Mais conteúdo relacionado

Mais procurados

INTERFACE, by apidays - The 8 Key Components of a Modern API Stack by Iddo G...

apidays

apidays LIVE Paris 2021 - 20 Minutes to Build a Serverless COVID-19 GraphQL A...

apidays

Wide adoption of Microservice Architecture presents a whole new set of challenges for us as developers. Some of them are well-known and understood. About others we do not think until they strike us out of the blue and we spend a lot of sleepless nights trying to figure them out. And communication between services in distributed system is one of the latter. During this Microservice Architecture Odesa #TechTalk we will talk about how to prevent your microservices from becoming a modern-world Tower of Babel. We will discuss how to select appropriate communication mechanisms for most common cases in a distributed system, how should we define API contracts for each of them and what tools are available for us to keep them consistent and evolve them over time. We will touch following topics:  REST vs RPC vs Messaging and how not to get lost with your options.  Contract First development and how it can save time in multi-team environment.  SwaggerHub as a single Point of truth for REST API  Best practices for gRPC contracts and how to deal with changes in them. About speaker: Andrii Barsukov is Senior .NET developer at Lohika, with 5+ years of commercial experience in development of microservice applications. Currently participating in development of microservice-based financial system, which includes 20+ microservices developed by 10 separate development teams. And some of the challenges that we faced during its development I'd like to share.

Design and Evolution of APIs in Microservice Architecture

Lohika_Odessa_TechTalks

Open API Initiative: Six months and counting

Open API Initiative (OAI)

apidays LIVE Paris 2021 - Automating API Documentation by Ajinkya Marudwar, G...

apidays

apidays LIVE Paris 2021 - Why GraphQL is Perfect For Microservices by Roy Der...

apidays

Like many other companies like it, NN Group is undertaking a digital transformation. APIs are the key enabler of this digital transformation. In 2017 they commenced the implementation of the API management solution using WSO2 software. They have engineered the WSO2 components in such a way to create an API Management infrastructure that is fully automated, both in provisioning, and operational management. WSO2 is now being used for managing external APIs. NN Group is now expanding its use to internal API management. This presentation focuses on the way they have engineered their external API management solution on the AWS cloud, how they implemented several CI/CD patterns to achieve zero down-time, and how they set up their API community.

[WSO2Con EU 2018] Implementing a Zero Downtime WSO2 API Manager with an API C...

WSO2

apidays LIVE Paris 2021 - Detecting and Protecting PII by Rob Dickinson, Resu...

apidays

apidays LIVE Australia 2021 - Confessions of a Product Geek : My First API BY...

apidays

apidays LIVE London 2021 - Quantum Duality of “API as a business” and “API as...

apidays

apidays LIVE Paris 2021 - EDI & API on One Integration Platform by Mir Mustha...

apidays

The Open API Initiative, s̶i̶x̶ Nine Months and Counting." Are you new to the OAI? At the Sept. 15, 2016 OAI Meetup, we started the evening with a brief overview of the Open API Initiative, some background on the Swagger Project that it's based upon, and how many companies today are collaborating to enable open governance of the OAS 3.0 Spec - as it approaches completion later this year. - presented by Jeff Borek, WW Program Director, Open Cloud Business Development, Software Group, IBM Corporation

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

Open API Initiative (OAI)

To view the recording of this webinar please use the below URL: http://wso2.com/library/webinars/2015/03/wso2-product-release-webinar-wso2-app-factory-2.1.0/ In this webinar, Manjula Rathnayaka, associate technical lead, and Kasun De Silva, software engineer at WSO2, will present the following new features and improvements to App Factory 2.1: Adding new application types by including an archive Ability to add runtime externally Puppet scripts for App Factory deployments WSO2 BAM integration for user activity Custom URL improvements

WSO2 Product Release Webinar - WSO2 App Factory 2.1

WSO2

Swagger & OpenAPI Spec #openapi

Muhammad Siddiqi

apidays LIVE Paris 2021 - Synchronous Communication Patterns by Sébastien Ber...

apidays

API Design Collaboration

Uchit Vyas ☁

How LISI Automotive Accelerated Application Delivery with SwaggerHub

SmartBear

apidays LIVE Hong Kong - Open Banking, Yin and Yang in Hong Kong by Simon Red...

apidays

Proliferating OpenAPI at Google

Open API Initiative (OAI)

This talk describes the development of ABN AMRO’s API handbook, the single-source of truth for the development and management of internal and external API products. Our company is moving towards an API-First culture and mentality. Streamlining the development process is key to enabling this. In the beginning, API development knowledge was not documented or centralized in one location. Accurate information was not available for developer teams and they were not aware of what exactly the process entailed. My colleague and I began by making agreements on how the overall process works, describing it in an intuitive way, and then by making it open and accessible company-wide. This involved setting up and hosting face-to-face meetings or MS Teams calls with specialists to find out what was required This talk describes our approach to gathering content from experts, defining and refining processes, obtaining feedback from readers, and redesigning the content in a more user-centric format.

Blood, sweat, and creating an API handbook

Pronovix

Mais procurados (20)