Join Stormpath .NET Developer Evangelist, Nate Barbettini, to learn best practices for designing your REST API in ASP.NET Core. Nate will explain how to build HATEOS-compliant JSON APIs while supporting security best practices and even improving performance and scale. Topics Covered: What is REST and HATEOS? How to think about RESTful APIs How to model hypermedia in C# Building JSON APIs in ASP.NET Core

1. BEAUTIFUL REST APIs
in ASP.NET Core
Nate Barbettini
@nbarbettini
recaffeinate.co
.ws

2. Welcome!
● Agenda
● Stormpath 101 (5 mins)
● REST APIs in ASP.NET Core (60 mins)
● Q&A (15 mins)
● Nate Barbettini
● Developer Evangelist @ Stormpath

3. 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

4. Stormpath User Management
User Data
User
Workflows Google ID
Your ApplicationsApplication SDK
Application SDK
Application SDK
ID Integrations
Facebook
Active
Directory
SAML

5. Overview
● What is REST?
● Why is API design important?
● HATEOAS (Hypertext As The Engine Of Application State)
● REST APIs in ASP.NET Core

6. REST vs. RPC
● REST: resources and collections of resources
● RPC: remote function calls

7. /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

8. 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.

9. Good REST design should...
● Be discoverable and self-documenting
● Represent resources and collections
● Represent actions using HTTP verbs
● KISS!

10. BEST PRACTICE #0
Plan API design from the beginning

11. Revisiting the API example
/users GET: List all users
POST: Create a user
/users/17 GET: Retrieve a single user
POST or PUT: Update user details
DELETE: Delete this user
/users/17/posts GET: Get the user’s posts
POST: Create a post
/users?lname=Skywalker
Search
/users/17?include=posts
Include linked data

12. BEST PRACTICE #1
Follow a design spec

13. A specification for REST+JSON APIs
The ION spec: https://github.com/ionwg/ion-doc

14. Getting a single user
GET /users/17
{
"meta": { "href": "https://example.io/users/17" },
"firstName": "Luke",
"lastName": "Skywalker"
}

15. Getting a list of users
GET /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"
}]
}

16. The starting point (API root)
GET /
{
"meta": { "href": "https://example.io/" },
"users": {
"meta": {
"href": "https://example.io/users",
"rel": ["collection"],
}
}
}

17. ● 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

18. LIVE CODING

19. Best practices recap
0. Plan API design from the beginning
1. Follow a design spec
2. Use async for database access
3. Write integration tests

20. Next steps
● Full example
https://github.com/nbarbettini/beautiful-rest-api-aspnetcore
● ION draft spec
https://github.com/ionwg/ion-doc

21. Thank you!
Nate Barbettini
@nbarbettini
recaffeinate.co
.ws