Bummer! This is just a preview. You need to be signed in with a Basic account to view the entire video.

Preview

Start a free Basic trial
to watch this video

Sign up for Treehouse

Endpoints

4:01 with Alena Holligan

Endpoints are the workhorses of our APIs. Let's talk about what they're expected to do and how to design them.

Download Postman

Choose your platform and you can download an auto-installer. There is no fancy setup. Just run the program like any other program on your computer.

Resource, Endpoint and Actions

A resource is a piece of data, which usually comes out of a database (but doesn't have to!). Resources are gathered together into collections. Resources are usually available at endpoints that point to either individual resources or collections of resources. Endpoints don't represent actions that you take on those resources, though. Actions are determined by the data provided to an endpoint and the HTTP method used to access the endpoint.

By combining endpoints and HTTP methods, we can build complete sentences with just HTTP and REST.

URL vs URI, what's the difference?

The acronyms URL and URI are often used interchangeably. Although they can be referencing the same thing, there are some distinctions. Here is a brief summary:

  1. URI stands for "Uniform Resource Identifier", the keyword being "Identifier". This can mean name, location, or both.
    • Example: /api/v1/games/1234
  2. URL stands for "Uniform Resource Locator", the keyword being "Locator" so it provides full details to locate the resource.
    • Example: https://teamtreehouse.com/alenaholligan
  3. The part that makes something a URL is the combination of the name and an access method, such as https://, or mailto:.
  4. URLs are URIs, but the opposite is not true. So saying URI is always technically accurate, but if you are discussing something that’s both a full URL and a URI (which all URLs are), it’s best to call it a “URL” because it’s more specific.

To learn more, visit the following resources:

  • 0:00

    When we talk about language, we have many different types of words, nouns,

  • 0:05

    verbs, adjectives, adverbs, etc.

  • 0:08

    When we talk about REST APIs,

  • 0:10

    we really only care about two of those word types, nouns and verbs.

  • 0:15

    Let's start by focusing on nouns.

  • 0:17

    A noun names something.

  • 0:20

    In a REST API, we have these somethings called resources.

  • 0:24

    What's a resource?

  • 0:26

    Usually it's a model in our application.

  • 0:28

    Maybe, again, you're holding onto players' scores for your game.

  • 0:32

    So a player would be a resource, and so would a score.

  • 0:36

    You might have other things too, like a match if they're playing against

  • 0:39

    other players, or a seed if your game levels were randomly generated.

  • 0:44

    These resources are things we want to be able to retrieve, create, or

  • 0:49

    modify through our API.

  • 0:52

    We do that retrieving, creating, and modifying, and even deleting,

  • 0:56

    at specific URLs which are called endpoints.

  • 1:00

    Endpoints represent either a single record or a collection of records.

  • 1:04

    For example, these two endpoints represent a collection of games and a single game.

  • 1:10

    We know that the second URL is a single resource

  • 1:13

    because of the identifier at the end of it.

  • 1:15

    The first one doesn't have anything that makes it specific.

  • 1:19

    Let's add a bit more here.

  • 1:21

    Hm, these new URLs don't really look right, do they?

  • 1:25

    I mean we can infer that the top one is again a list or collection URL, and

  • 1:30

    the bottom one is a detail, but they've changed their design quite a bit.

  • 1:35

    That second one should have the ID after the resource type.

  • 1:39

    And really, if we're going to use games we should use players.

  • 1:43

    Typically, your resource name should be plural.

  • 1:46

    Since the default action is to get a collection, and

  • 1:49

    you wouldn't call a collection of players, player.

  • 1:53

    Whether you use singular or plural names for your resources, keeping your URL

  • 1:58

    designs consistent goes a long way towards discoverability and usability of your API.

  • 2:05

    So now let's talk about verbs.

  • 2:08

    In language, verbs are actions.

  • 2:11

    They're things for doing or want to do.

  • 2:14

    In RESTful API design, they're actions you're going to take on resources.

  • 2:19

    But instead of being in your URL,

  • 2:22

    they're represented by the type of request the client makes to the API.

  • 2:27

    We have four main verbs, or HTTP methods, that we use for Rest APIs.

  • 2:33

    GET is used for

  • 2:34

    fetching either a collection of resources, or a single resource.

  • 2:39

    All of our previous URLs would be GET-able.

  • 2:43

    POST is used to add a new resource to a collection.

  • 2:47

    For example, we wouldn't POST to /players/567 or

  • 2:51

    /games/1234, because they aren't collections.

  • 2:56

    We would, however, post to /players or

  • 2:59

    /games to create a new player or a new game.

  • 3:03

    PUT is the HTTP method, or verb, that we use when we want to update a record.

  • 3:09

    We wouldn't use PUT on a collection or list URL.

  • 3:13

    And finally, we have the DELETE method.

  • 3:16

    I'm sure you can already guess what DELETE is used for.

  • 3:20

    Sending a DELETE request to a detail record, a URL for

  • 3:23

    a single record, should delete just that record.

  • 3:28

    Sending delete to an entire collection would delete the whole collection.

  • 3:33

    But that's usually not implemented, with good reason.

  • 3:37

    With a combination of nouns and verbs, we can write just about any sentence want,

  • 3:43

    at least within the constraints of our API.

  • 3:46

    In the next video, we'll use Postman to look at an actual request.

  • 3:50

    Check the notes associated with this video to download and

  • 3:54

    install Postman on your machine.

  • 3:56

    You can use it to test any API, not just what we do in this course.

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

Sign up