Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
REST, WebAPI 2, and Best Practices Keith Telle Lead Software Engineer Bit Wizards Gulf Coast DOTNET User Group May 19, 2015 http://www.gulfcoastdotnet.org @GCDNUG What is REST? • REpresentational State Transfer • Originally described by Roy Thomas Fielding, circa 2000 • Doctorial Dissertation • “Architectural Styles and the Design of Network-based Software Architectures” https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm • Chapter 5, “Representational State Transfer (REST)” https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm What is REST? • Coordinated set of constraints applied to web service design • • • • • • Client/Server Stateless Cachable Layered system Code on demand (optional) Uniform interface • • • • Identification of resources Manipulation of resources through these representations Self-descriptive messages Hypermedia as the engine of application state (HATEOAS) What is REST? • For Network-based data transference • Has widespread acceptance across the Web • Simpler than SOAP and WSDL-based Web services Why use REST? • Performance • User-perceived • Caching, reducing the average latency of a series of interactions • Most important information up front, retrieve additional details after rendering has begun • Stateless, reduced consumption of physical resources • Scalability • • • • Stateless Spread the interface across multiple servers Server doesn’t have to store state, allowing quick release of resources Easily cached using HTTP methods Why use REST? • Simplicity • Clean separation of concerns • Hides the underlying implementation of resources • Hides the underlying communication mechanisms • Modifiability • Separation of concerns, components can evolve independently • Visibility • Monitoring system does not have to look beyond a single request in order to determine the full nature of the request • Uniform interface Why use REST? • Portability • Separation of concerns, platform independence • HTTP services can reach a broad range of clients, including browsers, mobile devices, and traditional desktop applications • Reliability • Eases the task of recovering from partial failures How does REST work? • Everything has an ID • Allows you to map a URI to a resource • Examples http://example.com/customers/1234 http://example.com/orders/2007/10/776654 http://example.com/products/4554 http://example.com/processes/salary-increase-234 How does REST work? • Things are linked together • HATEOAS “Hypermedia as the engine of application state” • The idea of links in a document or resource • Can point to resources that are provided by a different application, a different server • Enables the client to move the application from one state to the next by following a link How does REST work? • Use standard HTTP methods • simple, flexible, and ubiquitous • GET : retrieve a resource • POST : create a resource • PUT : change the state of a resource or to update it • DELETE : remove or delete a resource How does REST work? GetCustomerDetails GET http://example.com/customers/123456/details How does REST work? • Uses HTTP Error Handling and Reporting • Align errors with HTTP status codes • Can provide body content to amplify • Verbose • Plain language descriptions • As many hints as the API team can think of about what's causing an error How does REST work? • HTTP Status Codes 200 201 304 400 401 Ok Created Not Modified Bad Request Not Authorized 403 404 405 415 500 Forbidden Page / Resource Not Found Method Not Allowed Unsupported Media Type Internal Server Error How does REST work? Your API Key is Invalid, Generate a valid API Key at http://… A User ID is required for this action. Read more at http://… Your JSON was not properly formed. See example JSON here: http://… How does REST work? • Resources may have multiple representations • Provide multiple representations of resources for different needs • JSON or XML • Also other formats such as iCalendar, vCard, etc. How does REST work? • Works statelessly • Not stateless, communicates statelessly • Turned into resource state or kept on the client • Scalability • Isolates the client from changes on the server • Physical and logical What does REST look like? Resource GET Collection URI, such ashttp://api.example.com/v1/re sources/ List the URIs and perhaps other details of the collection's members. Element URI, such ashttp://api.example.com/v1/re sources/item17 Retrieve a representation of the addressed member of the collection, expressed in an appropriate Internet media type. PUT POST Replace the entire collection with Create a new entry in the another collection. collection. The new entry's URI is assigned automatically and is usually returned by the operation.[9] Replace the addressed member of the collection, or if it does not exist,create it. ref. Wikipedia, Representational state transfer Not generally used. Treat the addressed member as a collection in its own right and create a new entry in it.[9] DELETE Delete the entire collection. Delete the addressed member of the collection. What is WebAPI 2? • Microsoft framework for creating REST web services • (alternative is ServiceStack framework, https://servicestack.net/) • Based on the Model-View-Controller pattern, built on ASP.NET MVC 5 framework • Model is an object that represents the data in your application • View is the API • Controller is an object that handles HTTP requests • Caller-independent web services (Javascript/JQuery, Angular, etc.) What are the features of Web API 2? • Routing http://example.com/users/711856 http://example.com/orders/233546 What are the features of Web API 2? public class UsersController : ApiController { … // GET: api/Users/5 public string Get(int id) { var user = UserRepository.Get(id); return user; } … } What are the features of Web API 2? • Attribute Routing http://example.com/users/711856/orders http://example.com/users/711856/orders/233546 http://example.com/users/711856/orders/233546/details What are the features of Web API 2? public class UsersController : ApiController { … [Route(“users/{userId}/orders”)] public IEnumerable<Order> GetOrdersByCustomer (int id) { var orders = UserRepository.GetOrders(id); return orders; } … } What are the features of Web API 2? • Serialization • XML Media-Type Formatter • JSON Media-Type Formatter • Selected via provided media type (HTTP headers) What are the features of Web API 2? • JSON Media-Type Formatter public class Product { public string Name { get; set; } public decimal Price { get; set; } [JsonIgnore] public int ProductCode { get; set; } } What are the features of Web API 2? • JSON Media-Type Formatter [DataContract] public class Product { [DataMember] public string Name { get; set; } [DataMember] public decimal Price { get; set; } public int ProductCode { get; set; } } What are the features of Web API 2? • Configuration var json = GlobalConfiguration.Configuration.Formatters.JsonFormatter; json.UseDataContractJsonSerializer = true; json.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver(); json.SerializerSettings.DateFormatHandling = Newtonsoft.Json.DateFormatHandling.MicrosoftDateFormat; json.SerializerSettings.DateTimeZoneHandling = Newtonsoft.Json.DateTimeZoneHandling.Utc; json.SerializerSettings.Formatting = Newtonsoft.Json.Formatting.Indented; What are the features of Web API 2? • Dynamic Objects public object Get() { return new { Name = "Alice", Age = 23, Pets = new List<string> { "Fido", "Polly", "Spot" } }; } What are the features of Web API 2? • Security, Authentication, and Authorization • ASP.NET Identity • Individual • The app uses a membership database • Organizational • Azure Active Directory, Office 365, or on-premise Active Directory credentials • Windows authentication • Intended for Intranet applications, and uses the Windows Authentication IIS module What are the features of Web API 2? • Security, Authentication, and Authorization • JSON Web Token (JWT) http://jwt.io/ • Using JSON Web Tokens with Katana and WebAPI by K. Scott Allen http://odetocode.com/blogs/scott/archive/2015/01/15/using-json-webtokens-with-katana-and-webapi.aspx What are the features of Web API 2? • Error Handling • HttpResponseException • HttpError What are the features of Web API 2? • HttpResponseException • Returns any HTTP status code that you specify in the exception constructor public Product Get(int id) { Product item = repository.Get(id); if (item == null) { var resp = new HttpResponseMessage(HttpStatusCode.NotFound) { Content = new StringContent(string.Format("No product with ID = {0}", id)), ReasonPhrase = "Product ID Not Found" }; throw new HttpResponseException(resp); } return item; } What are the features of Web API 2? • HttpError • Provides a consistent way to return error information in the response body public HttpResponseMessage Get(int id) { Product item = repository.Get(id); if (item == null) { var message = string.Format("Product with id = {0} not found", id); return Request.CreateErrorResponse(HttpStatusCode.NotFound, message); } return Request.CreateResponse(HttpStatusCode.OK, item); } What are the features of Web API 2? • API Reference • Creating Help Pages for ASP.NET Web API by Mike Wasson http://www.asp.net/web-api/overview/getting-started-with-aspnet-webapi/creating-api-help-pages • Cross origin resource sharing (CORS) • OWIN (Open Web Interface for .NET) self hosting, http://owin.org/ • Defines a standard interface between .NET web servers and web applications • Katana - OWIN implementations for Microsoft servers and frameworks What are the features of Web API 2? • IHttpActionResult public IHttpActionResult Get (int id) { Product product = _repository.Get (id); if (product == null) { return NotFound(); // Returns a NotFoundResult } return Ok(product); // Returns an OkNegotiatedContentResult } Best Practices • • • • • • • • • • Use nouns but no verbs GET method and query parameters should not alter the state Use plural nouns Use sub-resources for relations Use HTTP headers for serialization formats Use HATEOAS Provide filtering, sorting, field selection and paging for collections Version your API Handle Errors with HTTP status codes Allow overriding HTTP method Best Practices • Don’t think in terms of endpoints • Don’t expose your domain model in the API • Design your API after intent • Don’t overuse GET and POST • Don’t limit your choice of error codes to 200 and 500 • Don’t ignore caching • Don’t require versioning Best Practices • ASP.NET WEB API : Do's/Dont's and Best Practices https://curah.microsoft.com/204714/dosdonts-and-best-practices-ofaspnet-web-api • Best Practices for Designing a Pragmatic RESTful API http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api • ASP.NET Web API: A REST perspective http://devproconnections.com/aspnet/aspnet-web-api-rest-perspective • 10 Best Practices for Better RESTful API http://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-betterrestful-api/ Can I see it all in action? • Part 1: Building a simple REST service using WebAPI 2 Can I see it all in action? • Part 2 : Testing a REST service using POSTman • POSTman (Chrome application/extension) https://www.getpostman.com/ https://www.getpostman.com/docs • Interceptor (Chrome extension) https://www.getpostman.com/docs/capture Questions?