Designing RESTfulServices with ASP.NET Web APIfiles.meetup.com/12338682/DesigningRESTfulServices... · • Designing Evolvable Web APIs with ASP.NET ... • Building Hypermedia Web

1

Copyright © Brian Noyes 2013

www.solliance.net

Designing RESTful Services with ASP.NET Web API

Brian Noyes

CTO, Solliance Inc.

www.solliance.net

About Brian Noyes

CTO, Solliancewww.solliance.net

Microsoft Regional Director

Microsoft MVP

Pluralsight authorwww.pluralsight.com

www.solliance.net

t

e [email protected]

@briannoyes

http://briannoyes.net

Web API Insider, Windows Azure Insider,Window Store App Insider, C#/VB Insider

2


Agenda

• ASP.NET Web API Overview

• REST Overview

• Developing Web APIs and RESTful services

• Consuming Web APIs

ASP.NET Web API

• New platform for building HTTP web services (Web APIs)

• Built on top of ASP.NET MVC 4 framework• Released with .NET 4.5

• Compatible with .NET 4.0

• Just another Web Application project sub-type in VS 2013

• Makes it easy to build services for consumption from multi-platform clients

• Simple RPC services

• CRUD services

• REST services

• OData services

3


ASP.NET Web API

• Services are Controllers• ApiController class

• Leverages MVC features• Routing

• Model binding

• Action filters

ASP.NET Web API

• Convention over configuration• Maps URIs to controllers

• Maps HTTP verbs to methods / actions

• Maps URI / query string parameters to method parameters

HTTP/1.1

Request

GET http://localhost:2112/api/Customers/ALFKI?includeOrders=true HTTP/1.1

User-Agent: Fiddler

Host: localhost:2112

public class CustomersController : ApiController

{

public Customer GetCustomer(string id, bool includeOrders)

{ ... }

}

4


ASP.NET Web API

• Content negotiation• Based off HTTP Accept / Content-Type headers

• JSON / XML formatters out of the box

• OData formatter through NuGet

• Can plug in custom formatters

Request

GET http://localhost:2112/api/Customers/ALFKI HTTP/1.1

User-Agent: Fiddler

Host: localhost:2112

Accept: application/json

Response

HTTP/1.1 200 OK ...

Content-Type: application/json; charset=utf-8

Content-Length: 206

{"CustomerID":"ALFKI","CompanyName":"Alfreds Futterkiste"}

ASP.NET Web API Configuration

• No config file settings needed

• HttpConfiguration class• Associated with the ASP.NET web application instance

• Accessible from Global.asax code behind

• Calls WebApiConfig.Register

• Defaults are good enough for basic Web APIs

• Can plug in formatters, filters, message handlers and other custom extensibility objects through this class

public static class WebApiConfig

{

public static void Register(HttpConfiguration config)

{

config.Routes.MapHttpRoute(

name: "DefaultApi",

routeTemplate: "api/{controller}/{id}",

defaults: new { id = RouteParameter.Optional }

);

}

}

5


REST

• REpresentational State Transfer

• Focus on Resources and Representations instead of remote objects and operations

• REST is an architectural style, SOAP is a protocol

• Based on Ph.D. thesis: Roy Fielding

• REST fully embraces HTTPURI

HTTP Verb

HTTP HeadersHTTP Headers

Service address

Resource

Parameters

Operation

(POST,GET,PUT,DELETE)

Content Negotiation

Security, Etags, etc.

Payload

Status Codes

Media

Types

Hypermedia

HTTP Body

Web APIs vs REST

• Web APIs or Web HTTP services are not necessarily REST services

• REST is defined in terms of a set of architectural constraints

• Formal usage of REST vs common use of REST• Roy Fielding’s thesis

• REST in Practice, Jim Webber et al, http://shop.oreilly.com/product/9780596805838.do

• REST APIs must be HyperText drivenhttp://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

• Building Hypermedia Web APIs with ASP.NET Web APIhttp://msdn.microsoft.com/en-us/magazine/jj883957.aspx

• Building Hypermedia APIs with HTML5 and Nodehttp://shop.oreilly.com/product/0636920020530.do

6


REST Architectural Constraints

• Client-Server

• Stateless

• Cache

• Layered architecture

• Uniform Interface

• Code On Demand

Uniform Interface

• Identification of resources• URIs

• Manipulation of resources• HTTP Verbs• Representations• URI/Query string parameters• HTTP Status codes / headers

• Self-descriptive messages• Media types

• Hypermedia as the engine of application state (HATEOAS)

• Links identify related resources and available actions on the current resource

• Analogous to a service contract in SOA

7


Richardson’s Maturity Model

Level 0: POX / RPC

Level 1: URI / Resources

Level 2: HTTP

Level 3: Hypermedia

URI Design

• Service location

• Resource

• Parameters for manipulating the resource

• URL parameters or query string parameters

http://somesite.org/ResourceName/resourceId

http://somesite.org/ResourceName/ChildResource/resourceid/param

http://somesite.org/ResourceName?param1=a&param2=b

8


HTTP Services

• URI for service address + operation + parameters

• HTTP protocol • Verbs, headers, caching, status codes

• Content negotiation• Accept / Content-Type headers

• Media types

• HTTP Body• Contains representations of requested resource

Hypermedia-driven services

• Client only knows one URI

• Representations in responses contain hypermedia links• Links to related resources

• Action links to transition the resource to a new state

• Indicate allowable actions (operations) for that client for that resource for that point in time

9


OData as REST

• Standardized approach to CRUD Web APIs• Query syntax

• Complex filtering, ordering, paging, expanding, and selecting driven by the client

• OData formats

• ATOMPub XML, JSON Light, JSON Verbose

• Supports content negotiation

• Uses hypermedia linking• Relations

• Actions

Consuming REST APIs

• No metadata standard• No code generated proxies

• Theory:• Client only needs to know single root URI

• Reality:• Still need out-of-band information on media types and verbs

10


Consuming REST / Web APIs in .NET

• Old school• WebClient / HttpWebRequest

• New: HttpClient class• Available in .NET 4 / 4.5 and WinRT

• Async methods for GET, PUT, POST, DELETE

• Supports content negotiation

• Sample pluggable formatters as the server side

• Serializes strongly typed payload objects

Consuming REST/Web APIs in JavaScript

• Jquery, Angular, etc - AJAX• URL

• Method (verb)

• Content Negotiation (Accept/Content-Type headers)

• Handles JSON payloads natively

• Avoid XML

11


Thank You!

• Building Web API OData Serviceshttp://pluralsight.com/training/courses/TableOfContents?courseName=aspnetwebapi-odata

• Building End-to-End Multi-Client Service Oriented Applicationshttp://pluralsight.com/training/Courses/TableOfContents/building-multi-client-end-to-end-service-oriented-applications

• Roy Fielding Thesis:http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

• RESTful Web APIshttp://shop.oreilly.com/product/0636920028468.do

• Designing Evolvable Web APIs with ASP.NEThttp://chimera.labs.oreilly.com/books/1234000001708

• REST in Practice, Jim Webber et al, http://shop.oreilly.com/product/9780596805838.do

• REST APIs Must Be Hypermedia Drivenhttp://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

• Building Hypermedia Web APIs with ASP.NET Web APIhttp://msdn.microsoft.com/en-us/magazine/jj883957.aspx

www.solliance.net

t

e [email protected]

@briannoyes

http://briannoyes.net

Documents

Designing RESTfulServices with ASP.NET Web APIfiles.meetup.com/12338682/DesigningRESTfulServices... · • Designing Evolvable Web APIs with ASP.NET ... • Building Hypermedia Web