🥁First strategy #webinar of the year: 31 January❗ Join @kvantomme to learn about how to build your #strategy for c… https://t.co/pTIjAapD7s
Anabella Spinelli: Learning the OAuth Dance (Without Stepping on Anyone’s Toes)
Karen Sawrey: Disagree with “I Agree”. Enforcing Better GDPR Compliance Through the Language
Adam Kalsey: An API Is Not Enough: Crafting a Developer Experience
Sylvain Maudit: Beyond API Documentation: Designing a Hub for a Better Developer Experience
István Zoltán Szabó (Steve): Reference docs are not enough… even for internal developer portals
The API handyman, Author of The Design of Everyday APIs, Senior API architect
at Natixis
In his talk Arnaud draws parallels between the design of everyday objects and APIs. He focuses on the purpose, usability and constraints of the APIs.
Purpose First and foremost: to be an interface for developers - users shouldn’t be concerned about an API’s workings instead of what they can achieve with it Even great documentation cannot save a badly designed API
Usability Design objects to be straightforward and predictable for the user's satisfaction.
Straightforward design requires:
Predictable design means:
Constrained
By user context: latency/granularity, frequency/webhooks, streaming, volume/batch, bulk
By provider: scalability/rate limiting, performance/asynchronous, not 24/7/ no go
With enough time and money these can be solved in an ideal world - not where we live
Keywords to take away: empathy and context
"Documentation will not fix your bad design" @apihanyman #APIdesign #APIdocumentation pic.twitter.com/P7uAozj89K
— API the Docs (@APItheDocs) December 11, 2018
Software Engineer at Typeform
Anabella describes "the OAuth dance" by explaining her first encounter with it and what she and her team at Typeform learned from this experience.
2 main use cases
Authentication - login
Feature integration - the app will request data on a recurrent basis to provide a new, enhanced feature. This application needs to be registered in the provider’s platform to know who is asking for information: need a redirect URI
4 steps in the OAuth dance
Authorize
The app identifies itself through the user’s browser (public channel) requesting for specific information to be sent to a specific place
Consent
If everything’s OK with the above request Typeform will generate a consent screen. Interaction from Typeform to the user through the user’s browser. It contains: basic info, requested scopes, accept or cancel call to actions (pain point: error screen was blank - user cannot know what the problem is)
Redirection
From Typeform to My app’s redirect URI endpoint through the user’s browser a temporary code is sent to be used in the final step.
Token
Token request from app straight to Typeform without the browser. It contains client secret, temporary code, redirect URI.
Token granted from Typeform straight to the app without the browser.
How is the token used?
When the app wants something from Typeform, the unique token identifies:
which user does the data belong to
which app is requesting it and
whether it has the permissions to request that data.
Learnings
Test your guides with junior devs to find your blind spots - documentation should be aimed at this group
Have descriptive error states
Give people a map they can follow
Provide dev tools
Let's learn about oauth with @deutschevita from @typeform at #ApidaysParis #APIDays pic.twitter.com/vck9M7IOG0
— API Handyman (@apihandyman) December 11, 2018
Technical Writer/Editor at Cossack Labs
Karen summarizes the points to remember when you want to make your site GDPR compliant.
GDPR: enforces a security standard on documentation
APIdocs: something that can make GDPR more doable, more understandable for your users
The vicious circle of ignored documentation: Docs are hard to read -› People don’t read docs -› Why bother? Nobody reads docs anyway
GDPR on the surface
Use human language that users actually want to read
Intend to be concise and informative
Describe clearly what you are taking from people, what kind of data interaction is taking place
The secret life of docs beyond the surface:
Database storing emails and passwords
If you store your users’ data you are responsible for them - even if users are being “irresponsible” and use the same password for various sites - it is you responsibility in the first place to secure their passwords on your site
Use simple words in explanations
Keep your sandbox user data clean
Use warnings about security measures
Inform users about GDPR
Takeaway
There is no silver bullet for GDPR - you have to think for yourself - what data you need for what - minimize stored data
Privacy by design: how to enforce better #GDPR compliance with better #APIdocumentation? - @krnswry explains in her talk now.#APIdaysParis #APItheDocs pic.twitter.com/gMb7o9jnHg
— API the Docs (@APItheDocs) December 11, 2018
Webex Developer Relations at Cisco
Adam gives us the six principles for cracking a great developer experience both on internal and external developer portals.
Be user-centric: you can only provide a great developer experience (DX) if you have a deep understanding of the goals of your users.
Good/Great DX is your competitive advantage- so many substitutes for a developer product (other product, open source, even build one for themselves - overconfidence of the developer)
Reduce onboarding efforts - helps both provider and developer, on internal and external portal: saves time and effort
Internally it can also motivate tool building
6 principles of creating great DX
1. Easy to understand
What it is and isn’t designed for - documentation should be authentic and trustworthy - don’t market
Use terminology that your users do - don’t try to be unique with it - don’t make them learn you
2. Easy to use
Ease of signup
Tryout option without commitment - don’t use gatekeepers (keys, documentation, sandbox)
Provide in several programming languages
3. Easy to build
SDKs, code samples (use multiple styles), make the right thing the easy thing
Have consistency both in docs and in API design - API style guide
4. Easy to get help
Error messages in docs to make sure they’re easy to find
Release notes
Status page - honest and overcommunicating
5. Easy to trust
Uptime - trustworthy, honest
Clear communication about business plans
6. Easy to maintain
For the provider
Has to be baked into the product design
User experience is not only about (visual) design and it's not about the company it's about the users (hence the name, remember my Kitchen Radar 3000 in my session this morning) @akalsey #apidaysparis #APIdays pic.twitter.com/horqcMXl9Y
— API Handyman (@apihandyman) December 11, 2018
Information Architect and Technical Content Writer at Pronovix
Developer eXperience (DX) can play a crucial role in achieving business goals, but how can an organization motivate the developers who use its APIs?
Kathleen examines 23 public-facing developer portals in the banking and fintech industry: what features can reduce API friction?
According to the 6 stages of the downstream developer journey, you can opt for:
Landing page, API catalogue (stage 1: discover & research),
Blog, use cases, try-out & test options, trust signals like changelog, legal documentation (stage 2: evaluate),
Onboarding process elements, onboarding documentation, self-service support elements (stage 3: get started),
API references, FAQ pages, support options in 1 place, community page, discussion forum (stage 4: develop & troubleshoot),
Developer documentation, blog (guest post, interview), ask for feedback, events (stage 5: celebrate),
Release notes, status page, versioning info, legal documentation, revealing future plans (stage 6: maintain).
Throughout her talk, Kathleen gives us hands-on examples of tips and tricks, best practices and patterns.
Architecting developer experience by @kat_deroo #apidays #apidaysparis pic.twitter.com/AxrJ4Dsdtb
— API Handyman (@apihandyman) December 11, 2018
Senior Program Manager - Graph Developer Tooling at Microsoft
People either love or hate SDKs
What we really need is a kit - be able to pick and choose the parts that we want to use - users need to have choices
KIT components
Native library
Core library
Generated library
Workflow
Takeaways:
Separate request and content because it is versatile (thanks to HTTP) @darrel_miller #apidays #apidaysparis pic.twitter.com/7XqVWw7nXB
— API Handyman (@apihandyman) December 11, 2018
The API Handyman, Author of The Design of Everyday APIs, Senior API Architect
at Natixis
Even the best design intentions can fail.
The problem:
Resulting in:
Users losing time,
The API providing organization losing users and money.
The solution:
Follow an API style guide with defined rules to ensure consistency:
Workflow connected to set up an API style guide:
Write:
Raise awareness: share and promote,
Enforce and control:
Rules require governance.
@apihandyman is talking about the importance of #api styleguides at the @APItheDocs track on #apidaysparis. pic.twitter.com/TOp2McNaQe
— Szabó István Zoltán (@szabosteve) December 11, 2018
Lead API Evangelist/Engineering Manager at dailymotion
In his presentation Sylvain shares how dailymotion, as an API provider, decided to go beyond API documentation to design a hub for a better developer experience for its community.
How to create a great developer experience?
Basis
Good product and good documentation
Add extra layers
There were many visitors to stop by and listen to @Swop at the #apidays.
— dailymotionEng (@dailymotionEng) December 18, 2018
If you missed dailymotion’s Lead #API Evangelist’s #talk, here is your catch-up session! #REST #community #developers #ux https://t.co/tN4HgN1jfV
Technical Product Owner at HelloFresh
How do you apply product management to an internal platform team? Jessica shares some practical tips that her team has implemented successfully.
Why?
How?
Product management, in Jessica’s opinion, combines stakeholders, processes, communication and a vision.
Define your stakeholders:
Communicate well:
Implement predictable and transparent team processes to tackle work,
Use your vision on the project to prioritize what is important, and remove what is not:
Hear some tips about how to apply product management to internal teams by @JulyAte now at #APIdaysParis, #APItheDocs track pic.twitter.com/zLFNC1HbOt
— API the Docs (@APItheDocs) December 11, 2018
Developer Evangelist at Kaltura
External developers love the ease of using API client libraries in various languages, but what about your internal developers? Don’t they deserve an easy time as well?
Learn how to best automate your API Client Library Generation in order to efficiently save time and resources for your developers Avital presented a use case on what Kaltura does to make developers’ lives easier by offering client libraries.
Steps to follow:
Client library automation, inside out @avital_tzubeli #apidays #apidaysparis pic.twitter.com/EvT1K21iq8
— API Handyman (@apihandyman) December 11, 2018
Senior Technical Writer at Pronovix
A devportal (both internal & external) is a place for all stakeholders of your APIs, it is to assist in achieving your business goals. It is the place where you expose your API documentation.
Documentation types on developer portals:
The API description page provides an intro to the API:
Why?
How?
Steve introduces an API description page template for the technical writer and the workflow that goes with it:
An example with the (dummy) Nostromo API @szabosteve #apidays #apidaysparis pic.twitter.com/ugauefutPp
— API Handyman (@apihandyman) December 11, 2018
Original recording of the conference by Kristof Van Tomme, Creative Commons Attribution Share-Alike License v3.0
🥁First strategy #webinar of the year: 31 January❗ Join @kvantomme to learn about how to build your #strategy for c… https://t.co/pTIjAapD7s
We're excited to bring you the new virtual sessions of #APItheDocs focusing on the importance of #feedback #metrics… https://t.co/ifmptrM2bk
The #APItheDocs Virtual series returns in January, focusing on what is worth measuring on the community side of do… https://t.co/hS5D5ZzGg0
💡What are the essential elements of #developerportals? 💡How do you build a strategy that creates and catalyzes grea… https://t.co/5xstaoMV2w