The availability of cloud platforms like Windows Azure and the flexibility these offer makes it easier than ever to build highly scalable applications and services. It also gives developers access to an unseen level of scale and the ability to reach a bigger number of users. An important aspect to reach this scale is to embrace the “Bring Your Own Device” principle, where users will use your application from three screens: a phone, a tablet and a computer. To allow users to connect to your applications and to enable new extension scenarios, a solid Application Programming Interface is a must. It opens up all or partial functionalities in a controlled and secure way, built upon the HTTP standards which are supported in virtually any environment. In this session we will have a look at how you can start building your own API using ASP.NET MVC 4 Web Api, run it on Windows Azure and open up your services for multiple devices. We will see how easily you can re-use your MVC knowledge to build a solid API, how you can configure and extend the framework and how nicely it fits into the Windows Azure Platform. To secure our API, we will go through the OAuth protocol, which is an open and secure way to authorize API calls. To conclude we will talk about the various options you have when passing data back and forth, which formats you can use and what the impact on bandwidth could be, which is very important in scalable and cloud based scenarios.

1. #comdaybe
Windows Azure Applications
Made API
AZUG
Kristof Rennen

2. Who Am I?
• Kristof Rennen
• Architect at Capgemini Belgium
• Microsoft Extended Experts Team Member
• Crew member of the Windows Azure User Group Azug
• http://www.kristofrennen.be
• @kristofrennen

3. Agenda
• What is an API?
• Do we need one?
• ASP.NET Web API
• It’s all about HTTP
• API considerations
– Security
– Versioning
– Data formatting
– Design Guidelines
– Best practices
• Q&A

4. API’s

5. What is an API?
• Application Programming Interface
• Software-to-Software interface
• Contract between software and developers, a specification
– Offered functionalities
– Technical constraints (limits, ...)
– Constraints (legal, branding, ...)
– Use as offered by the vendor
• Programming instructions and standards
• Open services to other software developers (public or
private)

6. Do we need one?
• Reach to scale
• Smartphone generation
• BYOD with 3 screens: phone, tablet and
computer
• Self service
• Flexibility in providing content
• You have data to share
• Integration

7. Direct access
Concerns
• Caching
• Less flexible & more error
prone
• Tight coupling
• Less transparent
• Security (credentials and
connection string client
side)

8. Service based access
Answers
• Loose coupling, easy to
change
• Caching is easy
• Transparent
• Easily scalable
• Error handling
• Reusable

9. Build Richer Apps
Reach More Clients

10. API Growth
+ 100% + 50% + 3400% + 235% + 71% + 86% + 46% + 63%
Source: www.programmableweb.com – current APIs: 4535

11. ASP.NET Web API
• Part of ASP.NET MVC 4
• Framework to build HTTP Services (REST)
• Solid features
– Modern HTTP programming model
– Content negotiation (e.g. Xml, json, ...)
– Query composition (OData query support)
– Model binding and validation (conversion to .NET objects)
– Routes
– Filters (e.g. Validation, exception handling, ...)
– Testable
– IoC (service locator pattern)
– Flexible hosting (IIS, self hosting, ...)

12. It’s all about HTTP

13. It’s all about HTTP
• HTTP = Web
• Client / Server
• Atomic
• Cacheable
• Uniform interface
• Idempotence
• Resources

14. HTTP Methods
• GET: retrieval from server to client
• HEAD: = GET but only headers
• POST: append, annotate
• PUT: storage from client to server
• DELETE: remove identified resource

15. HTTP Codes
• Informational (1xx) (e.g. 100 - Continue)
• Successfull (2xx) (e.g. 200 - OK)
• Redirection (3xx) (e.g. 302 – Found)
• Client Error (4xx) (e.g. 401 –
Unauthorized)
• Server Error (5xx) (e.g. 500 – Internal
Server Error)

16. REST
• Representational State Transfer
• 6 constraints:
– Client / Server
– Stateless
– Cacheable
– Layered
– Code on demand
– Uniform interface

17. API Considerations

18. Security
• Access protected resources
• Identity, authentication and authorization
• Content security
• Use HTTPS if possible
• Don’t transmit important content in plain text
• Sanitize user inputs

19. Identity
• Who is making the API request?
• Usually a combination of a client id and a
client secret
• Limit number of requests, data volume,
...
• Which application is making the request
• Stored within the app

20. Authentication
• OpenID
• Authentication
• Standard
• Identity providers and
relying parties
• SAML, Certificates,
Username / Password

21. Authorization
• OAuth 2.0
• Open Authorization
• Standard
• Share private
resources
• Use of tokens:
specific resource,
specific right, specific
duration

22. Windows Azure?
Access Control Service
• Claim based
• Windows Identity
Foundation
• Identity providers:
facebook, google, yahoo,
live, adfs, openid
• OAuth 2.0 (draft)

23. Windows Azure?

24. Versioning
• Clients depent on a specific “version”
• Once public = never change
– Don’t change resource URIs
– Attribute / parameter position doesn’t matter
– Accept and ignore unknown attributes / parameters
• Design the URL scheme properly
– http://example.com/api/widgets.json (points to last version)
– http://example.com/api/v1/widgets.json
– http://example.com/api/v2/widgets.json
• Wait as long as possible to increase the version number
• Do your best to never, ever, break compatibility!

25. Windows Azure?
• Multi tenancy
• Web Api Routing
• Different version = different instance

26. Data Formatting
• Converts data between HTTP and Controller
world
• Knows about media types (as value of the
content-type header)
• Type of data sent in the body of the request and
response
• Accept header to allow content negotiation
• Using MediaTypeFormatter implementations
(custom implementation easy to add)

27. MediaTypeFormatter
• Knows about media types
• Tells API which content types are supported
• Can read and/or write
• Understands encoding and charset
• Has a stream to read (request) and to write
(response)
• Uses serialization and deserialization

28. Windows Azure?
• Proper data formatting directly influences
– Performance
– Scalability
– Throughput
– Bandwidth
– Cost

29. Design Guidelines
• Design your API for specific audiences
(e.g. Developers, application users, ...)
• Differentiate your API (why would people
use it)
• Easy to try, use and understand
• Less is more (start small)
• Documented

30. Best Practices
• API Health / Status page
(https://dev.twitter.com/status)
• Monitoring and Metrics
• Documentation
(https://dev.twitter.com/docs)
• Tryout console
(https://dev.twitter.com/console)
• Throttling & Quotas
(https://dev.twitter.com/docs/rate-limiting)

31. Takeaways

32. Keep in mind…
• Make it secure (OpenID, OAuth, ACS, …)
• Scale it separately
• Document properly (methods, errors, codes, types, versions, …)
• Grow piece by piece (start small)
• Build a community (more developers = more apps)
• Provision correct domains from the beginning
– api.something.com
– developer.something.com
– something.com
• Version from the beginning (or don’t)
• Think about localization and globalization

33. Resources
• Books
– API’s: A Strategy Guide
– REST API Design Rulebook
– Getting Started With OAuth 2.0
• Sites
– http://www.asp.net/web-api
– https://dev.twitter.com/
– https://developers.facebook.com/
– https://www.windowsazure.com/en-
us/home/features/identity/

34. Q&A

35. Windows Azure Applications Made API
Thanks! @kristofrenne