This course will be retired on June 1, 2025.

Heads up! To view this whole video, sign in with your Courses account or enroll in your free 7-day trial. Sign In Enroll

Building Services with ASP.NET Web API

Preview

Start a free Courses trial
to watch this video

Sign up for Treehouse

Designing Our REST API

6:55 with James Churchill

Now we're ready to design our REST API!

Follow Along

To follow along committing your changes to this course, you'll need to fork the aspnet-fitness-frog-spa repo. Then you can clone, commit, and push your changes to your fork like this:

git clone <your-fork>
cd aspnet-fitness-frog-spa
git checkout tags/v1.5 -b designing-our-rest-api

API Design Resources

If you'd like to learn more about designing APIs, check out the following resources:

HTTP Request Methods and Response Status Codes

For more information about HTTP request methods and response status codes, check out the following pages on MDN Web Doc:

API Versioning

If you'd like to learn more about how to version an API built with the ASP.NET Web API framework, check out the following resources:

Related Discussions

Have questions about this video? Start a discussion with the community and Treehouse staff.

Sign up

    Related Discussions

    Have questions about this video? Start a discussion with the community and Treehouse staff.

    Sign up

    As we saw in the demo the FitnessFrog client app supports 0:00
    the following user actions, viewing a list of entries, 0:04
    adding an entry, editing an entry, and deleting an entry. 0:08
    Let's use these user actions as our guide as we think through the design of our API. 0:13
    Before we start the design process, 0:19
    let's update the configuration of the client app. 0:21
    Open the client-app-config.json file in the root of the project. 0:24
    The client-app-configuration file just contains a single set in it, 0:29
    useInMemoryData. 0:35
    Changing this app setting to true, 0:36
    will cause the client app to use in memory client side data. 0:38
    This will allow us to excercise the client app without having a completed API. 0:42
    Save the file and start the application. 0:49
    And here's our list of entries. 1:01
    Notice that a banner is being displayed, 1:07
    letting us know that we're using the in-memory client-side data. 1:09
    Now, let's open the README mark down file in the root of our project. 1:15
    Here's a list of the user actions that our API needs to support. 1:25
    First up, viewing a list of entries, looks like we need an endpoint for 1:30
    an entries resource, which we can represent with a URI, entries. 1:35
    In addition to the resource URI we need an HTTP method. 1:53
    The GET HTTP method is used to request resource data from an endpoint. 1:58
    To support adding a new entry, we need a way for 2:06
    the client to get a list of the available activities and intensities. 2:09
    Let's plan to add end points for those resources, that'll support GET request. 2:18
    And to support creating the new entry, we need to plan on having our entry's 2:36
    endpoint support request containing the data for the new resource. 2:41
    To do that, we'll use the POST HTTP method, which will indicate to the API 2:45
    that the supplied request data should be added to the specified resource. 2:51
    To support editing and entry, we'll use the activities and 3:03
    intensities end points respectively to get the available values. 3:07
    We also need a way to get the existing values for the entry being edited. 3:11
    To do that, we can append the entry ID onto the entries resource URI. 3:17
    So, making a request against this URI using the GET HTTP method would result 3:25
    in a single entry being returned whose ID matches the supplied ID. 3:31
    And to support updating the entry we need our entries endpoint to 3:36
    support requests containing data for the updated resource. 3:40
    We can do that by adding support for the PUT HTTP method, 3:44
    which will indicate to the API that the supplied request data should 3:48
    replace in an existing data for the targeted resource. 3:52
    We'll only want to accept the PUT HTTP method on the URI that includes 3:56
    the resource ID, 4:00
    because we don't want to allow updates against an entire collection of resources. 4:01
    And lastly, to support deleting an entry we need our entries endpoint to support 4:07
    requests to delete specific resources. 4:12
    As you might guess, we can use the Delete HTTP method for that purpose. 4:14
    And just like we did with the PUT HTTP method, 4:19
    we only want to allow deletes on single resources, not the entire collection. 4:22
    So we need three resources, entries, activities and 4:29
    intensities that support these HTTP methods. 4:33
    We'll also want to return appropriate responses that 4:37
    use commonly used HTTP status codes. 4:41
    200 or OK which means that the request was 4:55
    successful and everything went okay. 4:59
    201 or Created. 5:04
    The request was successful and led to the creation of a resource. 5:08
    204 No Content. 5:15
    The request was successful and 5:20
    the client doesn't need to go away from its current page. 5:21
    Meaning, that the supplied data is now the current values for this resource. 5:24
    400 Bad Request. 5:31
    This indicates that the server couldn't understand the request due to invalid 5:35
    syntax. 5:39
    We'll use this status code when the supplied data is incomplete or 5:39
    doesn't validate. 5:44
    500 Internal Server Error. 5:45
    The server encountered unexpected condition or 5:49
    error that prevented it from fulfilling the request. 5:53
    While it's not a requirement,it is very common place when using web API to 5:56
    prefix all of your routers with API. 6:01
    That helps to ensure that the API routers won't collide with any 6:03
    NVC routers which you might have in your application. 6:08
    We currently aren't using NVC in our application, but there's a chance 6:11
    that we might need it in the future to provide help pages for our API. 6:15
    It's also commonplace for routes to include the version of the API. 6:32
    This helps to ensure the clients won't break when you make updates or 6:36
    improvements to your API. 6:40
    For now, we're building an API for a single client, so 6:42
    we're going to leave the version information out of our routes. 6:45
    For more information about how to manage versioning in Web API, 6:49
    see the teacher's notes. 6:53

    You need to sign up for Treehouse in order to download course files.

    Sign up

      You need to sign up for Treehouse in order to set up Workspace

      Sign up