Creating API’s -
The Do’s and Don’ts
of API Design
Simon Free
@simonfree

What to expect
The Basics
The different styles of API’s
Design and development workflow
How to plan
How to document
Security
oAuth
Everything in action
Summary

What is an API
Used in the software world for years
An interface for other developers to interact with your code
implemented to determine vocabulary and calling conventions between consumer and implementer
Great for sharing content and functionality

Why are API’s good?
An interface for other developers to interact with your code
No need for people to reinvent the wheel
Using other services speeds up development

Why create one?
Great for sharing content and functionality
Centralizes functionality (great for big business)
Allow other technologies to easily interact with your code
Allows you to focus on the core product, not the implementation

Different types of API’s
RESTful
Representational State Transfer
Base URI for all requests
Different mime types
Different http methods give different results
RPC
Remote Procedural Call
Standardized
think of directly accessing a cfc

RESTful API’s Explained
Multiple urls that have different meanings (easy to read)
http://api.simonfree.com/presentations/
http://api.simonfree.com/presentation/12.xml
http://api.simonfree.com/presentation/12/
POST and GET have different results
Multiple return formats available (optional but preferred)

The Development Process

Assignment

What is your goal?
Easy for developers to learn
Easy for developers to use
Difficult to be misused
Easy to maintain code that implements it
Powerful enough to fulfill requirements
Easy to extend
Appropriate to the audience

Planning
Talk to your users
Make use cases
LISTEN to your users
Create a 1 page spec
Write sudo code that would use the API
Update the spec
Rinse and repeat
Have other developers look at the spec

Setting Expectations
You will not be able to please everyone
Displease everyone equally
Expect to make mistakes
They will be flushed out in a few years
Expect the product to evolve

Know your potential issues
Poor planning can cause poor usability
An API reflects your product
Mistakes can not easily be fixed
You can add but you can’t remove
Must be accessible by all languages
Potentially opening up a HUGE security hole

SDR
Selective Data Retrieval
Your own database communication language
Allows for efficient data transfer
Requires additional documentation
Can be a security risk
Used by Facebook (fql)

Security
API’s can be dangerous
Planning of security is critical
API security can tie into your existing security model
Errors should never be displayed/returned

oAuth

oAuth

“An open protocol to allow secure API authorization in a simple and standard method from desktop and web applications.”
Simply, user credentials are never directly supplied, they are directed to the client site that authorizes them and returns a token
Good: Standardized and Secure
Bad: Confusing and mind melting

oAuth - Humor

oAuth - Flow

oAuth - Terms
Tokens:
Consumer
Request
Access
Secrets
Nonce

Documentation
Description
Parameters
Required
Name
Type
Description
Example Call
Example Response
Error Code

Documentation - Examples
Facebook (Good)
http://wiki.developers.facebook.com/index.php/API
Flickr (Good)
http://www.flickr.com/services/api/
Basecamp (Bad)
http://developer.37signals.com/basecamp/

Assignment Results

Execution
Create documentation for a simple API
Create a simple RESTful API
Create a site that uses the API

Future Developments

Keep an API accessible for at least 1 year (Ideally 2) after it has been depreciated
Keep depreciated functions active for 1-2 releases depending on frequency of releases
Gather user feedback
Keep an eye on developments in other technologies
Watch what other API developers are doing

Summary
DO

Summary
DO

Summary
DON’T

Summary
DO

Summary

Summary
DO

Summary

Summary
DO

Summary

Resources
http://hueniverse.com/oauth/
http://www.infoq.com/presentations/effective-api-design
(Article coming out soon)

That’s All!
Questions / Comments?
Simon@simonfree.com
Slides will be available at:
http://www.simonfree.com/presentations/
Follow me on Twitter:
http://www.twitter.com/simonfree