Pragmatic ASP.NET Web API Solutions - beyond ValuesController

Transcript

1. Pragmatic ASP.NET Web API Solutions - beyond ValuesController Christian Weyer christian.weyer@thinktecture.com think mobile!
2. 2 Christian Weyer • Solution architect and principal consultant at thinktecture • Focus on – Distributed applications, service orientation – Cloud computing – Interoperability, cross device – Pragmatic end-to-end solutions – Windows Server, ASP.NET, Web API, SignalR, WCF, Windows Azure – HTML5, JavaScript, AngularJS • Microsoft MVP for Windows Azure (Architecture) • ASP.NET Web API Advisory Board Member • http://blogs.thinktecture.com/cweyer • christian.weyer@thinktecture.com • @christianweyer think mobile!
3. 3 Topics – current selection • REST, RPC – whaaat? • Consuming • Web API design • Arbitrary data • Data validation • Optimizing • Push Services
4. 4 REST, RPC, and all that stuff
5. 5 Which one is ‚better‘?
6. 6 Which one is more ‚polite‘?
8. 8 http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
9. 9 In the end – it looks like this…
10. 10 Consuming Web APIs
11. 11 Consuming Web APIs • Nice thing is that HTTP works everywhere – .NET clients – Silverlight clients – Pure HTML(5) – JavaScript & jQuery – Android (Java) – iOS (Objective-C) – Embedded (C/C++) – Java – … you name it … • Combine that with JSON – and you are good to go – Native for JavaScript – Understandable by everybody (string parsing) – Compact-enough for .NET
12. 12 Designing Web APIs
13. 13 Shaping Web APIs
14. 14 Designing the shape of a Web API • First and foremost: it is all about the use cases! – Don’t implement blindly CRUD over everything – Think about what the client application(s) need to do – what the human user needs to see and work with • Web API is a use-case-optimized entry point • REST-ish or RPC-ish – Choose your route: • Face the facts: Domain model != Web API model – You may have an existing DB and domain model – You may have designed the domain model based on pure entity relations – Use case-optimized Web APIs have different shape routeTemplate: "api/{controller}/{action}/{id}",
15. 15 Implementing an ASP.NET Web API controller • “Mind the gap!” – Entities inside – Data Transfer Objects (DTOs) outside – may be optimized for transfer • dynamic data type ? • Mapping – From DTO to entity – From entity to DTO – Tools like AutoMapper may ease your life • Layers and layers and layers and…? – Do not over-architect and over-engineer – Often all your application does is deal with data • Data access with Entity Framework – Database-first: natural need to map to use-case-driven Web API shape – Code-first: can lead to too tight coupling
16. 16 Querying data • Do not blindly spit out lists of data that clients are requesting • Provide server-side paging (client-driven) – Can be implemented explicitly via method parameters – Passed by query string – Think about maximum number of items • Paging can also be solved with OData query syntax – Based on IQueryable – Plus a couple more: filtering, ordering • Can be used together with AutoMapper • Beware of exposing too much OData features through your controller – $select: select which properties to include (may be OK for use case) – $expand: expands related entities inline • OData query options can be limited
17. 17 Arbitrary data
18. 18 There is more than structured data • Need to transfer non-structured data – Send/upload documents, like images, PDFs – Get/stream documents • The web and HTTP handle this intrinsically – POST multipart MIME message to endpoint – GET binary data as streamed • ASP.NET Web API offers explicit support – Check for Request.Content.IsMimeMultipartContent and use MultipartFormDataStreamProvider – Return StreamContent in HttpResponseMessage • Any HTTP client can craft these POSTs
19. 19 Data validation
20. 20 System boundaries are… boundaries • Always validate incoming data – Validation on the incoming model, i.e. typically DTOs – DataAnnotations may be just enough • Automatic model validation in ASP.NET Web API – Check with ModelState.IsValid – Use an ActionFilter to return HTTP 400 (or 422) upon failed validation • Manual validation for multipart POSTs – Use GetBodyModelValidator from ASP.NET Web API configuration services • Internationalization of validation messages – May want to use custom, localized messages – Use .NET resources and hook them up via ASP.NET Web API configuration services
21. 21 Optimizing
22. 22 When the default is not the best • ASP.NET Web API always does full content negotiation upon each request • Replace IContentNegotiator on configuration services – E.g. pin to JSON only • JSON may not be compact or efficient enough on the wire • Implement custom MediaTypeFormatter – E.g. for Protocol Buffers (with protobuf-net) – Yet another case for optimized DTOs
23. 23 Push Services
24. 24 The world is not just request-response • Web APIs are your inbound API – From caller/consumer to service • Push Services are your outbound API – From service to caller/consumer • ASP.NET SignalR offers push-style communication – For any kind of application – Based on various transport protocols (WebSockets, SSE etc.) • Marry ASP.NET Web API with SignalR – Expose HubContext on ApiController – Call out to hub clients from inside Web API actions • Use OWN/Katana as hosting layer
25. 25 Summary • Web APIs are a means to model lightweight services – RPC-ish or REST-ful • ASP.NET Web API offers flexible pipeline to implement business needs • ASP.NET Web API & SignalR are a good team for realizing various communication patterns • Be pragmatic.
26. 26 Resources • http://blogs.thinktecture.com/cweyer • christian.weyer@thinktecture.com • ASP.NET Web API – http://www.asp.net/web-api • WebApiContrib – https://github.com/WebApiContrib • My samples – https://github.com/ChristianWeyer • thinktecture Open Source projects – http://thinktecture.github.com/