on the shoulders of giants learning about api design by looking backwards

On The Shoulders of GiantsLearning About API Design by Looking Backwards

Ronnie MitraPrincipal API Architect - EMEALayer 7 API Academy

Web APIs: New and Exciting!

http://www.flickr.com/photos/every1knows/4191971139

“Web APIs? I’ve been doing that for years.”

Image courtesy of http://www.flickr.com/photos/en321/3902138429/

Web APIs offer us a new perspective

http://www.flickr.com/photos/mugley/4407790613

What can we learn by looking back?

http://www.flickr.com/photos/dcassaa/483162086/

user-centered design makes things better

User-Centered Design:Design products for the users who will use them.

User InterviewsRapid PrototypingIterations

UCD helped drive websites into the world of web 2.0

Simpler look and feelIntuitive controlsFamiliar interfaces

UCD is all around us…and usually in our favourite products.

Can we apply a user centered design approach to web API design?

The challenge:Developers are a different breed of users.

We need to work on a developer-centered design approach for APIs

Identify audienceMake appropriate design decisionsPrototype and testIterate

Developer Centered Design

removing barriers will

increase adoption

We can learn a lot about registration from website design

Objective:Turn guest accounts into registered accounts

1. Communicate the value of registering2. Make it easy to signup3. Provide instant feedback4. Make policies clear5. Use “lazy registration”

Principles of Registration:

frictionless processes are good for API management.

security is war

Perfect security is not possible

Practical security = Make attacks inconvenient and too costly to execute

Protecting Websites:

1. TLS/SSL for data privacy and server AU2. User/password for authentication

Protecting SOA Services:

1. TLS/SSL for data privacy on the wire2. WS-* for message security

A1: InjectionA2: Cross-Site Scripting (XSS)A3: Broken Authentication and Session ManagementA4: Insecure Direct Object ReferencesA5: Cross-Site Request Forgery (CSRF)A6: Security MisconfigurationA7: Insecure Cryptographic StorageA8: Failure to Restrict URL AccessA9: Insufficient Transport Layer ProtectionA10: Unvalidated Redirects and Forwards

OWASP Top 10:

Is TLS/SSL Good Enough?

You need to configure it properly.You need to use a secure implementation

Website design: password policies

Don’t drive users away

The Lesson:Balance control with usability

hypermedia can make life

easier

Links allow us to navigate the web

Forms provide a template for input

Links and templates can make an API easier to use

documentation is a craft

APIs aren’t just for the web

What type of instructions do these APIs provide?

Think like a developer:

Information must be accessibleProvide information in small portionsThink task based

Good documentation improves usability

Examples are like illustrations.Use a LOT of them.

effective management

is critical

SOA Governance

Enforce access controlPromote service usageProvide service discovery documentsProvide service usage visibility

API Management

Enforce access controlPromote API usageProvide API documentationProvide API usage visibility

SOA Governance

How do we make sure that these services are used properly?

API Management

How do we get people to use our API without falling over?

Controlled versus Organic

Representing organizations is usefulComplexity sucksFocus on the user

What can we learn from SOA Governance?

abstraction saves time and

effort

In SOA, Enterprise Service Busses were useful

(but complicated)

TransformationContent-Based RoutingLoggingSecurity Enforcement

Off-loading security functionality makes sense

Provide consistent interfaces with a proxy

Summary

There is gold to be found when looking back

Don’t blindly lift and drop – adapt instead

Always make your design relevant to your developers

On The Shoulders of GiantsLearning About API Design by Looking Backwards

Ronnie MitraPrincipal API Architect - EMEALayer 7 API Academy