Building Beautiful REST APIs with ASP.NET Core
3 likes2,212 views
The document is a presentation by Nate Barbettini on creating REST APIs in ASP.NET Core, covering topics like the importance of API design, HATEOAS principles, best practices for API development, and a step-by-step guide to setting up a project. Key best practices include planning API design from the start, following a specification, using asynchronous database access, and writing integration tests. The presentation also provides links to resources and examples for further learning.
![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"
}]
}](https://image.slidesharecdn.com/webinarbuildingbeautifulrestapiswithasp-161215211415/85/Building-Beautiful-REST-APIs-with-ASP-NET-Core-15-320.jpg)
![The starting point (API root)
GET /
{
"meta": { "href": "https://example.io/" },
"users": {
"meta": {
"href": "https://example.io/users",
"rel": ["collection"],
}
}
}](https://image.slidesharecdn.com/webinarbuildingbeautifulrestapiswithasp-161215211415/85/Building-Beautiful-REST-APIs-with-ASP-NET-Core-16-320.jpg)
Building Beautiful REST APIs with 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