API Lifecycle, Methodology and Architecture

by Asad Khan @ Apistrat NYC (Feb. 2013)

Transcript

1. API Lifecycle, Methodology and Architecture Asad  Khan   Senior  Lead  Program  Manager   Microso4  Corp.  
2. uild on REST guidelines •  Resource should be uniquely addressable •  Standard way of applying verbs to nouns •  Messages should be self-descriptive •  Rely on HTTP status codes •  Resources should be connected to each other via hypermed
3. xample of RESTful services •  Twitter: •  http://twitter.com/statuses/user_timeline.xml?id=joelcomm •  http://twitter.com/statuses/user_timeline.xml?id=joelcomm&page= •  Google plus: •  https://www.googleapis.com/plus/v1/people/userId •  https://www.googleapis.com/plus/v1/people/me/activities/public? pageToken=CKaEL •  Facebook •  https://api.facebook.com/method/users.getInfo?uids=4
4. Why isn’t REST enough? Conventions are insufficiently prescriptive •  REST doesn’t define URL structure •  Representations vary dramatically •  Services require significant documentation •  REST doesn’t account for common patterns like search •  How do I filter results? •  How do I order results? •  Can I page results?
5. rescribes conventions that REST doesn’t •  Start with a similar set of foundational principles •  Addressable resources •  RESTful usage of HTTP verbs •  Hypermedia navigation •  Prescribes conventions that REST doesn’t •  Representation formats [AtomPub (RFC 5023), JSON (RFC 4627)] •  Precise verb meaning [HTTP (RFC 2616)] •  URL conventions for filtering, paging, etc [URI (RFC 3986)]
6. Demo
7. rescribes conventions that REST doesn’t •  Start with a similar set of foundational principles •  Addressable resources •  RESTful usage of HTTP verbs •  Hypermedia navigation •  Prescribes conventions that REST doesn’t •  Representation formats [AtomPub (RFC 5023), JSON (RFC 4627)] •  Precise verb meaning [HTTP (RFC 2616)] •  URL conventions for filtering, paging, etc [URI (RFC 3986)] OData  –  Open  Data  Protocol  (odata.org)  
8. RL Conventions •  OData  URL  components   •  hAp://.../MyService.svc/Employees/MyService.Manager?$top=5&$skip=5 •  URL  path  idenMfies  a  resource   •  hAp://.../Soupon.svc/Users(‘junhao’)/ReferredBy/ReferredBy/BillingAddre •  hAp://.../MyService.svc/Employees(1)/MyService.Manager/DirectReports •  URL  query  string  allows  selecMve  filtering  from  a  feed   •  hAp://.../Soupon.svc/Users?$top=5   •  hAp://.../Soupon.svc/Users?$filter=DisplayName  eq  ‘Hao  Chen’   Service  Root   Path   Query  String   EnMty  Set   Key  Segment   NavigaMon  Segments   Type  Cast  
9. filter L Conventions •  A  simple  property  match   •  hAp://.../Users?$filter=DisplayName  eq  ‘Hao  Chen’   •  Logical  operators:  eq,  ne,  gt,  ge,  lt,  le,  and,  or,  not   •  ArithmeMc  operators:  add,  sub,  mul,  div,  mod   •  String  funcMons:  substringof,  startswith,  concat,  length,  substring,  trim,  e •  Other  funcMons:  round,  floor,  ceiling,  year,  month,  day,  isof,  etc.   •  Any/all  (new  in  “OData  v3”)   •  hAp://.../Soupons?$filter=Ingredients/any(i:  substringof(‘garlic’,i))   •  Compound  condiMons  (can  be  arbitrarily  complex)   •  hAp://.../Users?$filter=year(LastSeenAt)  eq  2012  and  FavoriteTags/any(4 eq  ‘gazpacho’)  
10. orderby L Conventions •  Simple  ordering   •  hAp://.../Users?$orderby=DisplayName   •  More  advanced  ordering   •  hAp://.../Users?$orderby=ReferredBy/UserID   •  MulMple  field  ordering   •  hAp://.../Users?$orderby=year(LastSeenAt)  desc,  month(LastSeenAt)  des
11. top and $skip L Conventions •  Allow  client-­‐driven  paging   •  hAp://.../Soupons/?$top=2&$skip=2   •  Defaults  to  ordering  by  ID   •  Server-­‐driven  paging  uses  nextLink  as  an  opaque  token  
12. select and $expand L Conventions •  Column  filtering  (not  full  projecMons)   •  hAp://.../Users/?$select=DisplayName,FavoriteTags   •  Inclusion  of  related  enMMes   •  hAp://.../Users/?$select=ReferredBy/DisplayName&$expand=ReferredBy
13. ombining URL Conventions •  hAp://.../Soupons/   •  ?$top=2   •  &$skip=2   •  &$filter=Ingredients/any(i:  substringof(‘garlic’,  i)   •  &$orderby=RaMng  desc   •  &$select=Name,DescripMon,Ingredients   •  &$inlinecount=allpages   •  &$format=json  
14. OData - OASIS Technical Committee 69 total participants 20 companies  Key Sponsors §  Microsoft §  SAP §  IBM §  Mashery §  Citrix Systems §  Axway Software §  Progress Software §  Red Hat §  CA Technologies §  SDL §  Bank of America https://www.oasis-open.org/committees/tc_home.php? wg_abbrev=odata
15. ey Takeaways OData prescribes conventions that REST doesn’t •  Powerful set of URL conventions for filtering, paging, etc •  Payload conventions for simple and consistent serialization •  Well-known endpoints •  One entry point to the service for “dumb” clients •  Data model is defined at a public endpoint ($metadata) •  Provides a consistent model for batching requests and creating changesets One Set of libraries that can be shared •  iOS, Android, Windows Phone, Surface, Java, .NET, Phython, PHP… Rich application eco-system