Web-API-Best-Practices

Report
Web API Quick Start
HOW TO QUICKLY MAXIMIZE THE VALUE YOU ADD WITH WEB API
BRONZE SILVER
GOLD
CODE CAMP 2013 SPONSORS
Goal
To allow programmers experienced with creating services in
the Microsoft stack to quickly get going with Web API
About Me
Ryan Vice
Independent Consultant
[email protected]
www.RyanVice.net
Agenda
◦ Background and Motivations
◦ Quick Start
◦ Dealing with Mismatched Conventions
◦ Versioning
◦ Documenting Our API
Background and Motivations
API MODELING - RPC
ROUTE
ACTION
VERB
ARGUMENTS
\AccountManager\GetAccounts
Get all accounts
GET
none
\AccountManager\GetAccounts\:id
Get account by ID
GET
query string
\AccountManager\AddAccount
Add account
POST
header
\AccountManager\UpdateAccount
Update account
POST
header
\AccountManager\DeleteAccount
Delete account
POST
query string
\AccountManager\Deposit
Deposit funds
POST
header
\AccountManager\Withdraw
Withdraw funds
POST
header
Background and Motivations
API MODELING – RESOURCE CENTRIC
ROUTE
ACTION
VERB
ARGUMENTS
\Accounts
Get all accounts
GET
none
\Accounts\:id
Get account by ID
GET
query string
\Accounts
Add account
POST
header
\Accounts\:id
Update account
PUT
header
\Accounts\:id
Delete account
DELETE
header
\Accounts\:id\Deposit
Deposit funds
POST
header and query string
\Accounts\:id\Witdraw
Withdraw funds
POST
header and query string
Background and Motivations
EVOLVING FRAMEWORKS
◦ ASP
◦ ASP.Net Web Forms
◦ Server side controls
◦ Disconnected data access
◦ Data binding
◦ ASP.Net MVC
◦ Separation of Concerns
◦ Closer to the metal with HTTP
◦ ASP.Net Web API
◦ Content negotiation
◦ Fewer global objects
◦ Improved testability
◦ Integrated help page support
◦ Symmetrical client programming model
◦ Better HTTP support via strongly typed
HTTP Object Model
◦ Filter chaining (or filter pipeline) support
◦ Self-hosting
Background and Motivations
EVOLVING DESIGNS
◦ ASP
◦ Weak support for server side UX logic
◦ ASP.Net Web Forms
◦ Stronger support for server side UX logic
◦ Weak support for loosely coupled UX tier
◦ ASP.Net MVC
◦ Stronger support for looser coupling UX
tier
◦ Weak support for resource centric API
modeling
◦ ASP.Net Web API
◦ Stronger support for resource centric API
Modeling
Background and Motivations
ASP.NET MVC RPC STYLE JSON SERVICES
◦ Not resource centric
◦ Not good for multi-targeting
Background and Motivations
ASP.NET MVC RPC STYLE JSON SERVICES - API
ROUTE
ACTION
VERB
ARGUMENTS
\AccountManager\GetAccounts
Get all accounts
GET
none
\AccountManager\GetAccounts\:id
Get account by ID
GET
query string
\AccountManager\AddAccount
Add account
POST
header
\AccountManager\UpdateAccount
Update account
POST
header
\AccountManager\DeleteAccount
Delete account
POST
query string
\AccountManager\Deposit
Deposit funds
POST
header
\AccountManager\Withdraw
Withdraw funds
POST
header
Background and Motivations
ASP.NET MVC RPC STYLE JSON SERVICES - ISSUES
◦ Not resource centric
◦ Not good for multi-targeting or for public facing API
Background and Motivations
ASP.NET MVC RESOURCE CENTRIC STYLE JSON SERVICES - API
ROUTE
ACTION
VERB
ARGUMENTS
\Accounts
Get all accounts
GET
none
\Accounts\:id
Get account by ID
GET
query string
\Accounts
Add account
POST
header
\Accounts\:id
Update account
PUT
header and query string
\Accounts\:id
Delete account
DELETE
query string
\Accounts\:id\Deposit
Deposit funds
POST
header and query string
\Accounts\:id\Witdraw
Withdraw funds
POST
header and query string
Background and Motivations
ASP.NET MVC RESOURCE CENTRIC STYLE JSON SERVICES
◦ Resource centric
◦ Cumbersome to write
◦ Awkward routing
◦ Difficult to organize controller
◦ Requires extra code for content negotiation
◦ Magic strings for status codes
Quick Start
WEB API DEMO
Quick Start
ASP.NET WEB API RESOURCE CENTRIC STYLE JSON SERVICES - API
ROUTE
ACTION
VERB
ARGUMENTS
\Accounts
Get all accounts
GET
none
\Accounts\:id
Get account by ID
GET
query string
\Accounts
Add account
POST
header
\Accounts\:id
Update account
PUT
header
\Accounts\:id
Delete account
DELETE
header
\Accounts\:id\Deposit
Deposit funds
POST
header and query string
\Accounts\:id\Witdraw
Withdraw funds
POST
header and query string
Take Aways
◦
◦
◦
◦
Web Api makes it easier to create HTML friendly web services
Json.Net serializer allows offers a lot of benefits for making HTML friendly JSON
Help Pages allows you to get your services documented quickly
There are a few options for versioning your services, the most important thing is to pick one
Resources
◦Web API Official Page http://www.asp.net/web-api
◦APIGEE http://apigee.com/about/
◦Pluralsight http://www.pluralsight.com/
◦My Blog http://www.RyanVice.net

similar documents