Applying Design Priciples to APIs - 1 of 4

•

6 likes•2,708 views

This document discusses applying design principles to APIs. It is divided into four parts. Part I focuses on empathizing with developers by following best practices throughout the development cycle, handling errors transparently, and keeping the API status and methods clearly visible. The document provides checkslists of specific things API providers can do at each stage to be helpful, harmless, and honest from the developer perspective. Parts II through IV will cover additional design principles for APIs.

Technology

Applying Design Principles
to APIs
In Four Parts

Brian Mulloy
@landlessness

Apigee
@apigee

“Whatever is worth doing at all, is worth
doing well.”
-Philip Dormer Stanhope
Earl of Chesterﬁeld
1746

Baker’s Dozen
1. Development Cycle
2. Errors
3. Visibility
4. Flexibility-Usability Tradeoff
5. Hick’s Law
6. 80/20 Rule
7. Inverted Pyramid
8. Advance Organizer
9. Consistency
10. Self Similarity
11. Aesthetic-Usability Effect
12. Cost-Beneﬁt
13. Immersion

Four Parts

I. Empathize
Development Cycle ● Errors ● Visibility

II. Don’t Overwhelm
Flexibility-Usability Tradeoff ● Hick’s Law ● 80/20 Rule ● Inverted Pyramid

III. Don’t Reinvent the Wheel
Advance Organizer ● Consistency ● Self Similarity

IV. Be Beautiful
Aesthetic-Usability Effect ● Cost-Beneﬁt ● Immersion

Part I: Empathize
i. Development Cycle
ii. Errors
iii. Visibility

“ Successful products typically follow four stages
of creation: requirements, design,
development, and testing.

Development Cycle
Universal Principles of Design

Questions to ask at each phase:
1. What is the developer doing?
2. How can we help?

Share our domain knowledge
✓ Educate others about our domain
✓ Certify our partner developers

Point the way
✓ Inspire with an app gallery
✓ Guide the design of apps
✓ List the objects in our system

Share our API knowledge
✓ Engage developers with an API console
✓ Be accessible via forums, social media & email

Ask for input, give data
✓ Receive bugs & feature requests directly from developers
✓ Show each developer his API data

Development Cycle
Universal Principles of Design

✓ Educate others about our domain
✓ Certify our partner developers
✓ Inspire with an app gallery
✓ Guide the design of apps
✓ List the objects in our system
✓ Engage developers with an API console
✓ Be accessible via forums, social media & email
✓ Receive bugs & feature requests directly from developers
✓ Show each developer his API data

“ An action or omission of action yielding an
unintended consequence.

Errors
Universal Principles of Design

Make it easy to learn from mistakes
✓ Respond with HTTP status codes for apps
✓ Respond with verbose messages for app developers
✓ Create social error pages with details and hints

“ The usability of a system is improved when its
status and methods of use are clearly visible.

Visibility
Universal Principles of Design

Be transparent and human
✓ Broadcast system status and alerts
✓ Apologize for mistakes and give details
✓ Publish the API product roadmap

End of Part I: Empathize
i. Development Cycle
ii. Errors
iii. Visibility

Part 1: Checklist
✓ Educate others about our domain
✓ Certify our partner developers
✓ Inspire with an app gallery
✓ Guide the design of apps
✓ List the objects in our system
✓ Engage developers with an API console
✓ Be accessible via forums, social media & email
✓ Receive bugs & feature requests directly from developers
✓ Show each developer his API data
✓ Respond with HTTP status codes for apps
✓ Respond with verbose messages for app developers
✓ Create social error pages with details and hints
✓ Broadcast system status and alerts
✓ Apologize for mistakes and give details
✓ Publish the API product roadmap

THANK YOU
Questions and ideas to:

Brian Mulloy
@landlessness
brian@apigee.com

What's hot

jhipster-geekle-gbloch

Gaëtan Bloch

Devnest 110802

Angus Fox

JHipster is bad-ass. It's an Apache-licensed open source project that allows you to generate Spring Boot APIs and Angular (or React/Vue) apps. It has a vibrant community and ecosystem with support for deploying to many cloud providers and using the latest DevOps buzzwords, like Docker and K8s. This session will show you JHipster, why it's cool, and show you how to create an app with it. JHipster 7 Demo: https://www.youtube.com/watch?v=6lf64CctDAQ JHipster 7 Tutorial: https://github.com/mraible/jhipster7-demo#readme

Get Hip with JHipster - Colorado Springs Open Source User Group 2021

Matt Raible

The Epic Pivot: Heroku's Story

Adam Wiggins

Managing the lifecycle of software development can be a daunting task, especially after having adopted an Agile methodology that has you moving faster than ever. That is why it is more important than ever to have the right tools in place that allow you to effectively manage all facets of your SDLC from requirements gathering to testing and deployment. In the suite of tools available in the space of Application Lifecycle Management (ALM), Team Foundation Server (TFS) is a stand out. Let us show you how your organization can benefit from the advanced capabilities and unique configurability of TFS to successfully deliver your software development projects on time and on budget.

ALM with TFS: From the Drawing Board to the Cloud

Jeremy Likness

Google-IO-Presentation

Leo Chen

Automate Everyday Tasks with Functions

Sean ODell

Server-side Swift with Swagger

Chris Bailey

Mitchell levy repurposingcontent-13may15-1pgr

Mitchell Levy

How NOT to Suck at App Distribution - Quick Start Guide - Appsocially's Growt...

Yusuke Takahashi, PhD

I Love APIs 2015: MasterClass Developer Programs and Marketing Workshop

Apigee | Google Cloud

Avoiding Runaway Trains

Skot Carruth

So you have spent the last few years building PHP applications but now the business requirements have changed and you need to provide a full featured REST API. You could invest time, money and energy building it yourself, but have a look at Apigility. This is a full REST management application build on ZF2 allows you to tap into your existing legacy PHP application and provide 100% REST endpoints to the outside world. In this talk I go over the challenges we had to deal with creating our own REST implementation, throwing it all away because we only had 20% of the features of Apigility and setting up and managing Apigiltiy using our existing legacy PHP application. After this talk you will get a good understanding how to use Apigility to manage your REST API̢

Pimp legacy PHP apps with Apigility - TrueNorthPHP 2014

Michelangelo van Dam

Pitfall for WioLTE

Kouji Matsui

Speed up Continuous Delivery with BigData Analytics

Luca Milanesio

AIP Tutorial 4

Erik Ferlanti

Slack's Developer Relations Strategy - CMX Summit West 2016

CMX

Slides from HackExtend preparation event 2018, by Or Rosenblatt http://www.hackextend.com/ ------------------------- The superpower of a Hackathon is that after 24 hours, You have a product that people can actually enjoy and play around with. But how do you get there without wasting a lot of time on setup, integration or deployment? After all, we all like to sit and have a drink while watching the other teams at work. The DevOps culture offers us a lot of tools and practices that help us save time, deliver fast and get valuable feedback. Instead of writing code from scratch, you will learn how to use the advantages of the open source community. Join me and pick up some tips, tricks and solutions to deliver your ideas into a working product!

DevOps for Hackathons: DevOps without the Ops

Or Rosenblatt

Google IO 2018

Vishal Nayak

AEM responsive

Damien Antipa

What's hot (20)

jhipster-geekle-gbloch

Devnest 110802

Get Hip with JHipster - Colorado Springs Open Source User Group 2021

The Epic Pivot: Heroku's Story

ALM with TFS: From the Drawing Board to the Cloud

Google-IO-Presentation

Automate Everyday Tasks with Functions

Server-side Swift with Swagger

Mitchell levy repurposingcontent-13may15-1pgr

How NOT to Suck at App Distribution - Quick Start Guide - Appsocially's Growt...

I Love APIs 2015: MasterClass Developer Programs and Marketing Workshop

Avoiding Runaway Trains

Pimp legacy PHP apps with Apigility - TrueNorthPHP 2014

Pitfall for WioLTE

Speed up Continuous Delivery with BigData Analytics

AIP Tutorial 4

Slack's Developer Relations Strategy - CMX Summit West 2016

DevOps for Hackathons: DevOps without the Ops

Google IO 2018

AEM responsive

Similar to Applying Design Priciples to APIs - 1 of 4

Ronnie Mitra's slides from the Layer 7 Munich API Management Workshop. This workshop will included talks from Softcon CTO Michel Dorochevsky and Layer 7 API Architect Ronnie Mitra. The workshop Covered: • Discover the latest trends in the API economy • Understand why API Management is important • Learn best practices for securely exposing your APIs • Find out what other organizations are doing to manage their APIs

API Introduction - API Management Workshop Munich from Ronnie Mitra

CA API Management

Well Crafted API Models – Key to Streamlining Workflows

Axway

Scaling API Design - Nordic APIs 2014

Jason Harmon

Scaling API Design

Jason Harmon

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

apidays

Kevin Whinnery, Appcelerator Evangelist, shares best practices for creating mobile apps for cross-device deployment. Titanium Mobile is not a "write once, run everywhere" technology solution. Because Titanium provides the platform-specific APIs necessary to create best of breed native applications, the way in which you approach user interface development on one platform might differ significantly for another platform. It is, however, very possible to "write once, adapt everywhere" - to provide rich native experiences while achieving maximum code reuse. In this presentation, we will cover real world techniques for maximizing code reuse while leveraging platform-specific APIs in Titanium applications. Come with questions, and leave with multiple projects and code examples showing techniques Titanium developers use today to deliver sophisticated and performant cross-platform applications.

Kevin Whinnery: Best Practices for Cross-Platform Mobile Development

Axway Appcelerator

API Economy - Cuomo

Prolifics

10 Pitfalls to Avoid in Creating RIAs

EffectiveUI

10 Pitfalls to Avoid in Creating RIAs

Effective

APIs as a Product Strategy

Ravi Kumar

Spring is undoubtedly the most popular application development framework for enterprise Java. The key benefits of Spring framework emerge from its modularity, productivity, portability and testability. In this session, we have introduced you to development of cross platform applications using Spring. This will help you to understand the nuance of web, mobile and desktop application development with Spring. Contents * Why you cannot ignore cross platform development * Key architectural considerations * How to control cost and schedule with 'Responsive Web Design' * Role of Spring MVC in cross platform development * Useful tools in the bag * Comparing mobile frameworks with Spring * A few do's and don'ts for cross platform development * A live demo on how to build a cross platform application

Cross Platform Development with Spring

Cygnet Infotech

How to transfer from legacy system and legacy company to the brave new API world? Sharing some hands on experiences from 5 year journey in API development. “Rome wasn’t built in a day, nor should an API” so how should you prepare for the technological, organizational and business change: How do you change your sales, customer service and consultants to API sales, API customer service and API consultants? To solve or not to solve an integration problem with API? When UX problems changed to (API) service design problems?

Accidental API developer - the 12 month pregnancy to create new API

Marjukka Niinioja

Even though documenting APIs is a highly technical proposition, the contribution that a technical communicator can make to the documentation is not the same as that of the writing developer. In fact, API documentation is the place where we can shine and make the difference between failure and success of a product on the market. In this presentation, we'll see what makes good API documentation and how API writers can bring unique value to it. Presented at the tekom Spring Conference 2019 (Vienna).

Make Your Contribution Count. Adding Value to the API as a Technical Communic...

Petko Mikhailov

How do we reach developers and sustain a quality relationship with them? In this presentation, I cover tips on discoverability, support engineering, developer resource generation, and more, with the aim to create great developer programs that users trust and appreciate. But wait, there's a surprise! Liam Neeson will be our guide through this DevRel training montage. His lesson: Always mind your surroundings! This presentation was given at API City 2018 on Oct 4th.

Always Mind Your [Developer] Surroundings - API City 2018

Bill Doerrfeld

Use hackathons to gather data on the value of your API publishing program APIs are quickly becoming brands of their own and requiring product management strategies and marketing campaigns to be built around them to ensure they are effective. Hackathons provide a great way to grow developer awareness of APIs and attract the attention of thought leaders and influencers. But how do you demonstrate quantifiable ROI? Join this webinar with AT&T's Developer Evangelist, Alex Donn, TechCrunch's Hackathon Events Manager Leslie Hitchcock and Layer 7's API Evangelist, Alex Gaber to learn how you can get feedback and data from hackathons that will help you prove the value of your API program. You Will Learn Which ROI metrics business managers want to see What types of product research and testing you can conduct at a hackathon How to collect feedback and data at the event Presented by: Leslie Hitchcock Hackathon Events Manager TechCrunch Alex Donn Developer Evangelist AT&T Alex Gaber API Evangelist Layer 7

ROI for APIs: Using Hackathons to Evaluate Your API Program

CA API Management

Webinar on How to use MyAppConverter

Jaoued Ahmed

Every DevOps implementation is unique, but certain challenges are the same. Establishing fast feedback loops, formulating a better definition of done, and anticipating technical gaps to delivery are all milestones to transformation. In this session, our panel of experts will share their experiences in DevOps transformation. Learn how to: -Improve your team’s definition of done to cut down rework -Identify automation gaps that lead to later holding patterns -Inject fast feedback to catch bugs as early as possible -Establish autonomy and ownership over winning customer-focused experiences

Four Keys to Efficient DevOps

Perfecto by Perforce

Following the tagline for 2019’s Platform Summit, I will seek to examine the role web APIs are playing in improving efficiency and scalability across enterprises. In the modular world of microservices development, containers, Kubernetes, and quick deployment styles are all the rage. I’ll take a look at specific of APIs at work within DevOps, and point out new frontiers where API-first designs are improving development and interoperability standards for today’s most powerful digital platforms.

Continuous API Strategies for Integrated Platforms

Bill Doerrfeld

One of the greatest challenges to developing an API is ensuring that your API lasts. After all, you don’t want to have to release and manage multiple versions of your API just because you weren’t expecting users to use it a certain way, or because you didn’t anticipate far enough down the roadmap. In this session, we’ll talk about the challenge of API Longevity, as well as ways to increase your API lifecycle including having a proper mindset, careful design, agile user experience and prototyping, best design practices including hypermedia, and the challenge of maintaining persistence.

Building a REST API for Longevity

MuleSoft

Today, digital technology leaders and their IT teams are facing mounting pressure to meet demand for the creation and management of digital experiences (i.e. websites and beyond), driven by new business initiatives such as digital marketing campaigns, global branding, and security and compliance standards. In addition to executing ever-growing site delivery requests, IT teams are pressed to accommodate internal requirements for content flexibility, cost efficiency, and continuous multisite performance - often causing conflicting obligations. To meet expectations, for both quantity of sites delivered and quality of service, digital IT teams must re-evaluate their approach to site management and process governance. They must evolve their technologies and services, and make the necessary changes to become a ‘center of excellence’ for their organizations. In this webinar, we will cover the following topics: - How to transform your IT digital team from a “bottleneck” to a trusted service provider - How to implement a site governance strategy across your organization - Best practices for expediting website development and delivery

5 Steps to Delivering Many Sites, Lowering Costs, and Improving Governance

Rachel Wandishin

Similar to Applying Design Priciples to APIs - 1 of 4 (20)

API Introduction - API Management Workshop Munich from Ronnie Mitra

Well Crafted API Models – Key to Streamlining Workflows

Scaling API Design - Nordic APIs 2014

Scaling API Design

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

Kevin Whinnery: Best Practices for Cross-Platform Mobile Development

API Economy - Cuomo

10 Pitfalls to Avoid in Creating RIAs

APIs as a Product Strategy

Cross Platform Development with Spring

Accidental API developer - the 12 month pregnancy to create new API

Make Your Contribution Count. Adding Value to the API as a Technical Communic...

Always Mind Your [Developer] Surroundings - API City 2018

ROI for APIs: Using Hackathons to Evaluate Your API Program

Webinar on How to use MyAppConverter

Four Keys to Efficient DevOps

Continuous API Strategies for Integrated Platforms

Building a REST API for Longevity

5 Steps to Delivering Many Sites, Lowering Costs, and Improving Governance

Recently uploaded

This talk focuses on the practical aspects of integrating various telephony systems with Salesforce, drawing on examples from implementations in the Czech scene. It aims to inform attendees about the spectrum of telephony solutions available, from small to large scale, and their compatibility with Salesforce. The presentation will highlight key considerations for selecting a telephony provider that integrates smoothly with Salesforce, including important questions to support the decision-making process. It will also discuss methods for integrating existing telephony systems with Salesforce, aimed at companies contemplating or in the process of adopting this CRM platform. The discussion is designed to provide a straightforward overview of the steps and considerations involved in telephony and Salesforce integration, with an emphasis on functionality, compatibility, and the practical experiences of Czech companies.

Integrating Telephony Systems with Salesforce: Insights and Considerations, B...

CzechDreamin

IOS-PENTESTING-BEGINNERS-PRACTICAL-GUIDE-.pptx

Abida Shariff

Designing Great Products: The Power of Design and Leadership by Chief Designe...

Product School

New customer? New industry? New cloud? New team? A lot to handle! How to ensure the success of the project? Start it well! I've created the 3 areas of focus at the beginning of the project that helped me in multiple roles (BA, PO, and Consultant). Learn from real-world experiences and discover how these insights can empower you to deliver unparalleled value to your customers right from the project's start.

Powerful Start- the Key to Project Success, Barbara Laskowska

CzechDreamin

The standard Salesforce Approval process can be limiting in many ways, especially in complex scenarios. What if there was a way to implement very flexible approvals where one can use Apex code to make data updates in unrelated records, dynamically generate next steps details, and compute assignees on the fly? And still use UI-based configurations to implement concrete approval processes. In this session, we will share ideas behind such a solution and show a few lines of code to get you started.

Custom Approval Process: A New Perspective, Pavel Hrbacek & Anindya Halder

CzechDreamin

How world-class product teams are winning in the AI era by CEO and Founder, P...

Product School

How to differentiate Sales Cloud and CPQ on first glance might be tricky if you do not know where to look and what to look at. You will know :-) Managing the sales process within Salesforce is a common use case that can be managed with standart Sales Cloud. If you want to do entire quoting process you will find out Salesforce CPQ solution exists. What is then the difference if both can handle selling products? You will see comparison of 10 different features, which Sales Cloud and Salesforce CPQ handle differently. Simple question you will always remember if you should consider using Salesforce CPQ will be a cherry on top.

10 Differences between Sales Cloud and CPQ, Blanka Doktorová

CzechDreamin

UiPath Test Automation using UiPath Test Suite series, part 3

DianaGray10

GenAISummit 2024 May 28 Sri Ambati Keynote: AGI Belongs to The Community in O...

Sri Ambati

I'm excited to share my latest predictions on how AI, robotics, and other technological advancements will reshape industries in the coming years. The slides explore the exponential growth of computational power, the future of AI and robotics, and their profound impact on various sectors. Why this matters: The success of new products and investments hinges on precise timing and foresight into emerging categories. This deck equips founders, VCs, and industry leaders with insights to align future products with upcoming tech developments. These insights enhance the ability to forecast industry trends, improve market timing, and predict competitor actions. Highlights: ▪ Exponential Growth in Compute: How $1000 will soon buy the computational power of a human brain ▪ Scaling of AI Models: The journey towards beyond human-scale models and intelligent edge computing ▪ Transformative Technologies: From advanced robotics and brain interfaces to automated healthcare and beyond ▪ Future of Work: How automation will redefine jobs and economic structures by 2040 With so many predictions presented here, some will inevitably be wrong or mistimed, especially with potential external disruptions. For instance, a conflict in Taiwan could severely impact global semiconductor production, affecting compute costs and related advancements. Nonetheless, these slides are intended to guide intuition on future technological trends.

Future Visions: Predictions to Guide and Time Tech Innovation, Peter Udo Diehl

Peter Udo Diehl

💥 Speed, accuracy, and scaling – discover the superpowers of GenAI in action with UiPath Document Understanding and Communications Mining™: See how to accelerate model training and optimize model performance with active learning Learn about the latest enhancements to out-of-the-box document processing – with little to no training required Get an exclusive demo of the new family of UiPath LLMs – GenAI models specialized for processing different types of documents and messages This is a hands-on session specifically designed for automation developers and AI enthusiasts seeking to enhance their knowledge in leveraging the latest intelligent document processing capabilities offered by UiPath. Speakers: 👨‍🏫 Andras Palfi, Senior Product Manager, UiPath 👩‍🏫 Lenka Dulovicova, Product Program Manager, UiPath

Dev Dives: Train smarter, not harder – active learning and UiPath LLMs for do...

UiPathCommunity

When stars align: studies in data quality, knowledge graphs, and machine lear...

Elena Simperl

Are you looking to streamline your workflows and boost your projects’ efficiency? Do you find yourself searching for ways to add flexibility and control over your FME workflows? If so, you’re in the right place. Join us for an insightful dive into the world of FME parameters, a critical element in optimizing workflow efficiency. This webinar marks the beginning of our three-part “Essentials of Automation” series. This first webinar is designed to equip you with the knowledge and skills to utilize parameters effectively: enhancing the flexibility, maintainability, and user control of your FME projects. Here’s what you’ll gain: - Essentials of FME Parameters: Understand the pivotal role of parameters, including Reader/Writer, Transformer, User, and FME Flow categories. Discover how they are the key to unlocking automation and optimization within your workflows. - Practical Applications in FME Form: Delve into key user parameter types including choice, connections, and file URLs. Allow users to control how a workflow runs, making your workflows more reusable. Learn to import values and deliver the best user experience for your workflows while enhancing accuracy. - Optimization Strategies in FME Flow: Explore the creation and strategic deployment of parameters in FME Flow, including the use of deployment and geometry parameters, to maximize workflow efficiency. - Pro Tips for Success: Gain insights on parameterizing connections and leveraging new features like Conditional Visibility for clarity and simplicity. We’ll wrap up with a glimpse into future webinars, followed by a Q&A session to address your specific questions surrounding this topic. Don’t miss this opportunity to elevate your FME expertise and drive your projects to new heights of efficiency.

Essentials of Automations: Optimizing FME Workflows with Parameters

Safe Software

Welcome to UiPath Test Automation using UiPath Test Suite series part 2. In this session, we will cover API test automation along with a web automation demo. Topics covered: Test Automation introduction API Example of API automation Web automation demonstration Speaker Pathrudu Chintakayala, Associate Technical Architect @Yash and UiPath MVP Deepak Rai, Automation Practice Lead, Boundaryless Group and UiPath MVP

UiPath Test Automation using UiPath Test Suite series, part 2

DianaGray10

Explore the core of Salesforce success in 'Salesforce Adoption – Metrics, Methods, and Motivation.' We will discuss essential metrics, effective methods to drive adoption, and the driving force behind user engagement and explore strategies for onboarding, training, and continuous support that empower users to navigate the platform seamlessly. By leveraging these tools, you can effectively measure adoption against your company’s goals and create an environment where users not only adopt Salesforce but actively contribute to its ongoing success.

Salesforce Adoption – Metrics, Methods, and Motivation, Antone Kom

CzechDreamin

Already know how to write a basic SOQL query? Great! But what about an *aggregate* SOQL query? You know, the kind that uses aggregate functions like COUNT & MAX along with GROUP BY and HAVING clauses? No? Well, get ready to learn how to slice & dice your org’s data right inside your own dev console. From finding duplicate records to prototyping summary & matrix reports, learn the ins and outs of aggregate queries during this fast-paced but admin-friendly session on advanced SOQL concepts.

SOQL 201 for Admins & Developers: Slice & Dice Your Org’s Data With Aggregate...

CzechDreamin

Unsubscribed: Combat Subscription Fatigue With a Membership Mentality by Head...

Product School

De-mystifying Zero to One: Design Informed Techniques for Greenfield Innovati...

Product School

Screen flow is a powerful automation tool that is commonly designed for internal and external users. However, what about the guest users? We will dive into various methods of launching screen flows and understand how to make them publicly accessible, extending their usability to a broader audience. The presentation will also cover the implementation of security layers and highlight best practices for a smooth and protected user experience. Discover the potential of screen flows beyond conventional use and learn how to leverage them effectively.

Free and Effective: Making Flows Publicly Accessible, Yumi Ibrahimzade

CzechDreamin

We're living the AI revolution and Salesforce is adapting and bring new value to their customers. Einstein products are evolving rapidly and navigating their limitations, language support, and use cases can be challenging. Let's make review of what Einstein product are available currently, what are the capabilities and what can be used for in CEE region and how Rossie.ai can help to learn Salesforce speak Czech. We will explore the Einstein roadmap and I will make a short live demo (based on your vote) of some Einstein feature.

AI revolution and Salesforce, Jiří Karpíšek

CzechDreamin

Recently uploaded (20)