Building beautiful REST APIs with ASP.NET Core Nate Barbettini @nbarbettini 

About me  Developer Advocate @ Okta  Microsoft MVP  Blog @ www.recaffeinate.co  Tweet @nbarbettini 

What is REST? REST != returning JSON over HTTP REST = an abstraction with specific rules REST = all about resources and links 

RPC vs. REST REST (Representational State Transfer) • Endpoints are nouns (resources): api.example.io/users • Calling the endpoint acts on the resource: GET api.example.io/users/123 POST api.example.io/users/123 • Typically returns the resource that was acted upon RPC (Remote Procedure Call) • Endpoints are verbs (methods): api.example.io/getUser • Calling the endpoint calls the method: GET api.example.io/getUser POST api.example.io/updateUser • Returns the result of the function call 

Bad RPC vs. Clean REST GET /getAllAccounts GET /getAccount?id=17 POST /createAccount POST /update?accountId=17 GET /findAccount?lastname=Skywalker GET /accounts GET /accounts/17 POST /accounts POST /accounts/17 GET /accounts?lastname=Skywalker 

HATEOAS (hypermedia as the engine of application state)  Data exchange should be treated as if the client were a web browser  No documentation or out-of-band info needed GET wikipedia.org English Español Deutsch 

REST + JSON is popular but it's really hard because there’s no spec. 

The Ion hypermedia type  Plain ol’ JSON  Resources and collections  Links and HATEOAS 

Ion objects (resources) { "title": "Who is the coolest Avenger?", "createdAt": "2017-07-24" } "href": "https://api.posts/conversations/123", GET https://api.posts/conversations/123 

Ion links { "href": "https://api.posts/conversations/123", "title": "Who is the coolest Avenger?" "createdAt": "2017-07-24", "author": { "href": "https://api.posts/users/iron_man" }, "comments": { "href": "https://api.posts/conversations/123/comments", "rel": ["collection"] } } GET https://api.posts/conversations/123 

Ion collections { "href": "https://api.posts/conversations/123/comments", "rel": ["collection"], "value": [ { "href": "http://api.posts/comments/456", "body": "Iron Man of course", "conversation": { "href": "/conversations/123" } }, { "href": "http://api.posts/comments/789", "body": "wait a sec...", "conversation": { "href": "/conversations/123" } } ] } GET https://api.posts/conversations/123/comments 

Building on ASP.NET Core 

Why ASP.NET Core  Fast  Clean  Modern  Familiar 

Live coding 

More resources  Example code https://github.com/nbarbettini/BeautifulRestApi  Video course http://bit.ly/restapicourse  Ion draft spec https://ionwg.org Thanks for your time! @nbarbettini https://www.recaffeinate.co