172

I have heard both "resource" and "endpoint" to refer to the same thing. It seems that resource is a newer term.

What is the difference between them? Does "resource" imply a RESTful design?

1
  • 2
    Quoting Fielding: There is no such thing as a REST endpoint. There are resources. A countably infinite set of resources bound only by restrictions on URL length. Sep 17, 2021 at 1:57

6 Answers 6

145

REST

Resource is a RESTful subset of Endpoint.

An endpoint by itself is the location where a service can be accessed:

https://www.google.com    # Serves HTML
8.8.8.8                   # Serves DNS
/services/service.asmx    # Serves an ASP.NET Web Service

A resource refers to one or more nouns being served, represented in namespaced fashion, because it is easy for humans to comprehend:

/api/users/johnny         # Look up johnny from a users collection.
/v2/books/1234            # Get book with ID 1234 in API v2 schema.

All of the above could be considered service endpoints, but only the bottom group would be considered resources, RESTfully speaking. The top group is not expressive regarding the content it provides.

A REST request is like a sentence composed of nouns (resources) and verbs (HTTP methods):

  • GET (method) the user named johnny (resource).
  • DELETE (method) the book with id 1234 (resource).

Non-REST

Endpoint typically refers to a service, but resource could mean a lot of things. Here are some examples of resource that are dependent on the context they're used in.

URL: Uniform "Resource" Locator

  • Could be RESTful, but often is not. In this case, endpoint is almost synonymous.

Resource Management

Dictionary

Something that can be used to help you:

The library was a valuable resource, and he frequently made use of it.

Resources are natural substances such as water and wood which are valuable in supporting life:

[ pl ] The earth has limited resources, and if we don’t recycle them we use them up.

Resources are also things of value such as money or possessions that you can use when you need them:

[ pl ] The government doesn’t have the resources to hire the number of teachers needed.


The Moral

The term resource by definition has a lot of nuances. It all depends on the context it's used in.

3
  • 1
    I suspected the same. Have you seen any references that explain or document this?
    – B Seven
    Jun 1, 2015 at 18:54
  • Added some links that give a feel for each of the terms. Jun 1, 2015 at 19:09
  • 1
    Just adding that "endpoint" is a technical aspect whereas "resource" a logical one.
    – DaveX
    Jan 18, 2021 at 21:17
112

The terms resource and endpoint are often used synonymously. But in fact they do not mean the same thing.

The term endpoint is focused on the URL that is used to make a request.
The term resource is focused on the data set that is returned by a request.

Now, the same resource can often be accessed by multiple different endpoints.
Also the same endpoint can return different resources, depending on a query string.

Let us see some examples:

Different endpoints accessing the same resource

Have a look at the following examples of different endpoints:

/api/companies/5/employees/3
/api/v2/companies/5/employees/3
/api/employees/3

They obviously could all access the very same resource in a given API.

Also an existing API could be changed completely. This could lead to new endpoints that would access the same old resources using totally new and different URLs:

/api/employees/3
/new_api/staff/3

One endpoint accessing different resources

If your endpoint returns a collection, you could implement searching/filtering/sorting using query strings. As a result the following URLs all use the same endpoint (/api/companies), but they can return different resources (or resource collections, which by definition are resources in themselves):

/api/companies
/api/companies?sort=name_asc
/api/companies?location=germany
/api/companies?search=siemens
4
  • 4
    nicely explained 👍🏻 Aug 26, 2018 at 12:10
  • 1
    "As a result the following URLs all use the same endpoint (/api/companies), but they can return different resources." I mean no offence but you're really just making up your interpretation here. In terms of REST, these are just locations of different resources. The endpoint part you've tried to account for as some other part of the URL. It's because you're a programmer and you're thinking of how its implemented, as a piece of code at a single action method. Imagine that all these different URLs were routed and served from 4 servers are they all the same endpoint? It makes no sense now. Nov 29, 2018 at 17:12
  • 1
    The reason query strings are not part of endpoints is because endpoint isn't part of the language of REST nor a URL. It just isn't. You're thinking in terms of coding the handling web application. REST mentions nothing about query params or sorting or anything. It just doesn't. If you use /orders to return a collection and /orders?top=10 that's just pretty URLs, its no more or less RESTful than using links to /32knre32nj for the collection and a link to /a-b-c-d for the top ten orders. They're just resource identifiers. URLs can't be more or less RESTful and an endpoint isn't a thing. Nov 30, 2018 at 19:35
  • Just to add, a critical part of REST is the linking, such that a consumer need to not care for the resource identifiers, much I don't care what the URL is sitting behind the Add Comment button here. When we stop thinking in endpoints and pretty URLs and instead to hyperlinks where the URL is incidental, its much easier to design nice workflow based APIs on the interaction goal - I want to search for a company so that x - your API should be a journey to x where searching is in the middle of the flow to the eventual application state. Dec 1, 2018 at 12:09
11

Possibly mine isn't a great answer but here goes.

Since working more with truly RESTful web services over HTTP, I've tried to steer people away from using the term endpoint since it has no clear definition, and instead use the language of REST which is resources and resource locations.

To my mind, endpoint is a TCP term. It's conflated with HTTP because part of the URL identifies a listening server.

So resource isn't a newer term, I don't think, I think endpoint was always misappropriated and we're realising that as we're getting our heads around REST as a style of API.

Edit

I blogged about this.

https://medium.com/@lukepuplett/stop-saying-endpoints-92c19e33e819

1

According https://apiblueprint.org/documentation/examples/13-named-endpoints.html is a resource a "general" place of storage of the given entity - e.g. /customers/30654/orders, whereas an endpoint is the concrete action (HTTP Method) over the given resource. So one resource can have multiple endpoints.

1
  • 1
    Sorry @Dafka, but you are wrong. An endpoint has nothing to do with the verb (HTTP method like GET, POST, PUT, DELETE, PATCH) that is being used on it.
    – Jpsy
    May 25, 2018 at 7:24
1

1. Resource description “Resources” refers to the information returned by an API.

2. Endpoints and methods The endpoints indicate how you access the resource, while the method indicates the allowed interactions (such as GET, POST, or DELETE) with the resource.

Additional info: 3. Parameters Parameters are options you can pass with the endpoint (such as specifying the response format or the amount returned) to influence the response.

4. Request example The request example includes a sample request using the endpoint, showing some parameters configured.

5. Response example and schema The response example shows a sample response from the request example; the response schema defines all possible elements in the response.

Source- Reference link

1

Consider a server which has the information of users, missions and their reward points.

  1. Users and Reward Points are the resources
  2. An end point can relate to more than one resource
  3. Endpoints can be described using either a description or a full or partial URL

enter image description here

Source: API Endpoints vs Resources

0

Your Answer

Reminder: Answers generated by Artificial Intelligence tools are not allowed on Stack Overflow. Learn more

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.