6. “ The real issue is about design: designing
things that have the power required for the
job while maintaining understandability, the
feeling of control, and the pleasure of
accomplishment.
-Donald Norman
10. URL Design Versioning
Plural nouns for /dogs Include version in /v1/dogs
collections URL
ID for entity /dogs/1234 Keep one previous /v1/dogs
version long /v2/dogs
Associations /owners/5678/dogs
enough for
POST GET PUT DELETE
developers to
4 HTTP
migrate
Methods
Bias toward /dogs (not animals)
concrete names Errors
Multiple /dogs.json 8 Status Codes 200 201 304 400 401 403 404 500
formats in URL /dogs.xml
Verbose messages {"msg": "verbose, plain language hints"}
Paginate with ?limit=10&offset=0
limit and offset
Query params ?color=red&state=running
Client Considerations
Partial selection ?fields=name,state
Client does not ?suppress_response_codes=true
Use medial "createdAt": 1320296464 support HTTP
capitalization myObject.createdAt; status codes
/convert?from=EUR&to=CNY&amoun Client does not GET /dogs?method=post
Use verbs for GET /dogs
non-resource t=100 support HTTP
GET /dogs?method=put
requests methods
GET /dogs?method=delete
Search /search?q=happy%2Blabrador Complement API 1. JavaScript
with SDK and code 2. …
DNS api.foo.com 3. …
developers.foo.com libraries
15. Twitter Streaming API
Authorization: Basic aWhlYXJ0OmFwaXM=
Amazon Web Services API
Authorization: AWS
AKIAIOSFODNN7EXAMPLE:frJIUNo//yllqDzg=
Google API
Authorization: Bearer 1/fFBGRNJru1FQd44AzqT3Zg
33. Follow Netflix and the Web Linking spec
<link
href=“http://api-public.netflix.com/catalog/people/100637”
rel=“http://schemas.netflix.com/catalog/person.actor”
title="Elijah Wood”
></link>
48. Inline Base64 Encoding
POST /photos
{
“caption”: “Cool picture of my cat.”
“photo”: “RHVkZSwgbXkgY2F0IGhhcyB0aGUgYmVzdCBwYWphbWFzLg==”
}
49. 2-Step Process
POST /photos
{
“caption”: “Cool picture of my cat.”
}
PUT /photos/1234/data
Content-Type: image/jpeg
Content-Length: 240
Content-Transfer-Encoding: binary
…binary content…
67. Summary
• Checkout previous editions for URI design
• Start with API modeling
• Use OAuth for security
• Good message design is for developers
• Learn from hypermedia specs
• More on transactions later
71. THANK YOU
Contact us at:
@landlessness
brian@apigee.com
@kevinswiber
kswiber@apigee.com
@apigee
Editor's Notes
Creative Commons Attribution-Share Alike 3.0 United States License
“The argument is not between adding features and simplicity, between adding capability and usability. The real issue is about design: designing things that have the power required for the job while maintaining understandability, the feeling of control, and the pleasure of accomplishment.” – Donald Norman, “Simplicity Is Not The Answer”, ACM Interactions, volume 15, issue 5. “We are faced with an apparent paradox, but don't worry: good design will see us through. People want the extra power that increased features bring to a product, but they intensely dislike the complexity that results. Is this a paradox? Not necessarily. Complexity can be managed. “ – Donald Norman, “Simplicity Is Not the Answer”, ACM Interactions, volume 15, issue 5.
http://www.flickr.com/photos/mattharvey1/5712604622/We’re building a cathedral. Though it is complex, it must be beautiful.
What security measures can we put around our API?
http://www.flickr.com/photos/brent_nashville/2156695472/in/photostream/Collaborate with all stakeholders: marketing, business analysts, software engineers, key business people, etc. This will be your API team.Develop a ubiquitous language, a glossary of terms that will appear in your API. This keeps everyone on the same page.Document a mental model of your API. (How you do this is up to you. See: UML)Iterate.
http://www.flickr.com/photos/theory/3364213389/in/photostream/Freedom is fantastic until you hit the wall of reality. Your API represents your organization. Make sure your organization is present on key decisions.
What security measures can we put around our API?
Twitter uses HTTP Basic authentication. It has been around for a long time.Amazon Web Services chose to roll their own. This may have pre-dated the OAuth 1.0 specification.Google is using Bearer tokens with the OAuth 2.0 Framework specification.
We like OAuth2. It’s a standard, which means anyone can read how it’s done. There are also good libraries out there to help build this for your API.OAuth2 allows developers to build clients that take advantage of user resources located on other services, such as Facebook, Google, and GitHub.A good alternative is using OAuth 1.0a. LinkedIn uses OAuth 1.0a for authorizing clients in their API, and it works very well.Keep an eye on stronger access token algorithms. OAuth2 MAC token support is still an Internet-Draft.
What security measures can we put around our API?
What security measures can we put around our API?
What security measures can we put around our API?
What security measures can we put around our API?
What security measures can we put around our API?
What security measures can we put around our API?
What security measures can we put around our API?
What security measures can we put around our API?
What security measures can we put around our API?
What security measures can we put around our API?
What security measures can we put around our API?
What security measures can we put around our API?
What security measures can we put around our API?
What security measures can we put around our API?
Netflix uses Web Linking (RFC5899). Links have a relation value that may contain standard or custom relation types. An href is included as a link to follow based on that rel value.GitHub repos contain an organization object that has a URL one can follow. Note: GitHub does follow the Web Linking spec for certain links. They include a Link header with prev and next links.
We prefer the Web Linking style, which can be expressed in both XML and JSON styles. It adheres to a standard that anyone can follow. Also, we can utilize the standard link relations where appropriate.
GitHub’s API prefers an out-of-band approach. The alternative is based on HTML forms. Here’s a snippet of the Siren format using actions.
Inline form-style actions provide greater insight to developers exploring the API via HTTP. It allows the server to maintain control of the preferred method, href, and fields. This approach allows for easier inclusion of hidden field values the server deems necessary. Note: This is still emerging and is not yet widespread.
Flickr includes metadata such as number of views, server, and favorites inline with the data representation. Dropbox has a separate metadata resource that returns its metadata.
Actually, we think both these options are good. If the amount of metadata is relatively small, including it inline makes a lot of sense, as it’s less overhead than creating a brand new resource.If metadata happens to be very large, as may be the case for Dropbox, adding a separate resource may make sense. At this point, the metadata itself may be important enough to your API consumers to warrant a new resource. This is a good topic for discussion during an API modeling exercise.Metadata can also include response times, pagination counts, etc.
Simultaneous presentation of information and controls such that the information becomes the affordance through which the user obtains choices and selects actions.Not a linear progression, more of a directed acyclic graph.Offers choices for users to select actions.Offers links to related representations.
ALPS example from rstat.us.
ALPS example from rstat.us.
Links, Queries, Write Templates
Properties, Entities, Actions, Links
Benefits: Only one HTTP call. Binary files can be sent in binary format—more compact than base64. HTTP tools to handle this.
Benefits: Quick to implement. Good for small files.
Benefits: Good for larger binary files.
Just choose one method of submitting binary data in your API. Think about the options, how big your binary data will be, and where you want to go in the future. Even though there are trade-offs to each approach, they’re all capable.
30 Days
Yes, it’s important to not beat up your API server with requests. It’s also important to let client knows if they can save a round-trip to your server.
