building beautiful rest apis with asp.net core
TRANSCRIPT
Welcome!
● Agenda● Stormpath 101 (5 mins)● REST APIs in ASP.NET Core (60 mins)● Q&A (15 mins)
● Nate Barbettini● Developer Evangelist @ Stormpath
Speed to Market & Cost Reduction
● Complete Identity solution out-of-the-box● Security best practices and updates by default● Clean & elegant API/SDKs● Little to code, no maintenance
Stormpath User Management
User Data
User Workflows Google ID
Your ApplicationsApplication SDK
Application SDK
Application SDK
ID Integrations
Active Directory
SAML
Overview
● What is REST?● Why is API design important?● HATEOAS (Hypertext As The Engine Of Application State)● REST APIs in ASP.NET Core
/getAccount?id=17
Bad REST API design
/getAllAccounts
/updateAccount?id=17
/createAccount
/findPostsByAccountId?account=17
/accountSearch?lname=Skywalker
/getAccount?id=17&includePosts=1
/getAccount?id=17&format=json
/countAccounts
/partialUpdateAccount?id=17
/getPostCount?id=17
/deleteUser
HATEOAS, yo!"A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations." ~ Dr. Fielding
Tl;dr The API responses themselves should document what you are allowed to do and where you can go.
If you can get to the root (/), you should be able to “travel” anywhere else in the API.
Good REST design should...● Be discoverable and self-documenting● Represent resources and collections● Represent actions using HTTP verbs● KISS!
Revisiting the API example
/users GET: List all usersPOST: Create a user
/users/17 GET: Retrieve a single userPOST or PUT: Update user detailsDELETE: Delete this user
/users/17/posts GET: Get the user’s postsPOST: Create a post
/users?lname=SkywalkerSearch
/users/17?include=postsInclude linked data
A specification for REST+JSON APIs
The ION spec: https://github.com/ionwg/ion-doc
Getting a single userGET /users/17
{ "meta": { "href": "https://example.io/users/17" }, "firstName": "Luke", "lastName": "Skywalker"}
Getting a list of usersGET /users
{ "meta": { "href": "https://example.io/users", "rel": ["collection"] }, "items": [{
"meta": { "href": "https://example.io/users/17" }, "firstName": "Luke", "lastName": "Skywalker"}, { "meta": { "href": "https://example.io/users/18" }, "firstName": "Han", "lastName": "Solo"}]
}
The starting point (API root)GET /
{ "meta": { "href": "https://example.io/" }, "users": { "meta": { "href": "https://example.io/users", "rel": ["collection"], } }}
● Install the .NET Core SDK - http://dot.net/core● If you’re using Visual Studio:
○ Install the latest updates (Update 3)○ Install the .NET Core tooling - https://go.microsoft.com/fwlink/?LinkID=827546○ Create a new project from the ASP.NET Core (.NET Core) template○ Pick the API subtemplate
● Or, with Visual Studio Code:○ Use dotnet new -t web to create a new web project○ Run dotnet restore to restore NuGet packages
● Ready to run!
Getting started with ASP.NET Core
Best practices recap
0. Plan API design from the beginning1. Follow a design spec2. Use async for database access3. Write integration tests
Next steps
● Full example
https://github.com/nbarbettini/beautiful-rest-api-aspnetcore
● ION draft spec
https://github.com/ionwg/ion-doc