I'm brainstorming designing a REST API endpoint for a POST request, which extracts data out of some documents which i provide in the payload and stores it in database or some temporary location . Also i need GET and DELETE endpoints for retrieving and deleting extracted data . I am trying to figure out a resource name which justifies the output of this data-extraction process which i believe is extracted data and also complies with REST API conventions of not naming a resource name as a verb but a noun . Going by the REST API conventions , the resource which we are dealing with is only extracted-data . We cannot name it something like POST /extract-data as it becomes a verb . Or something like POST /data-extraction also not qualifies according to me , as it looks more like a process name than a resource . What i believe is that doing a POST request to extract data, i am providing objects/documents as input and in the output all i create is extracted-data, i can GET the extracted-data, and also i can DELETE the extracted-data, making it the resource which i can deal with . So based on my thought process ,
I think of below endpoints :
(i.) POST /extracted-data
(ii.) GET /extracted-data/{id}
(iii.) DELETE /extracted-data/{id}
Do above endpoints is really a good resource naming for the stated use-case or is there a better way to do it ?
Remember, REST doesn't care what spelling conventions you use for your resource identifiers, so long as they are consistent with the production rules in RFC 3986.
We cannot name it something like POST /extract-data as it becomes a verb
https://www.merriam-webster.com/dictionary/extract
The spelling of the identifier doesn't matter, because the method token is the "primary source of request semantics"
Because the machines don't care, we have an extra degree of freedom. So we can design the URI to get more of something else that we want. For instance, by aligning it with the name that human beings would use when talking about the resource.
Resources, in the context of REST are generalizations of documents. The world wide web is the reference implementation of the REST architectural style; the interesting resources on the web are "web pages".
Resources aren't "actions", they are web pages that are modified by actions. So you want to choose an identifier that aligns well with the name of the web page/document/resource, rather than choosing an identifier that aligns with the action of the change.
Related
A situation where I want a URL for list of values for a filter a URL for best match out of them to be returned.
Example data is as follows
/studentInformation?student=Albert&class=3&rollno=13&marks=24 will return 2 entries as no value is a value of interest to me
/studentInformation/bestMatch?student=Albert&class=3&rollno=13&marks=24 will return 1 value which is the best match i.e entry no 3 (limiting to 1 would not find the best match)
what is the right way to form the URL for best match?
REST doesn't have a standard for designing URI. It just says that every resource should have one.
On the web, we have a standard that describes the production rules for URI (RFC 3986) and a standard that describes URI Templates (RFC 6570), but neither of those get into the level of detail that you seem to be asking for.
And that's on purpose: URI on the web are a lot like variable names in a programming language; it's more generally useful to afford you the freedom to make local decisions about spelling conventions.
The machines don't care about semantic relationships between the spelling of the URI and the information of the resource, so you can choose any spelling that makes things better for people (where people here could be customers looking at the URI in their browser history, or pasting it into emails, or operators looking at URI in web logs, or writers trying to document your resource model, or even just the programmers trying to implement the API).
What would be a rest API convention to get a resource based on a different identificator?
For example
GET
/resource/{id}
GET
/resource/{guid}
Since this could be considered as a dupliate resource and setting routes for this could be a problem, what is an alternative then would follow rest API guidelines?
Maybe
/resources/?guid={guid}
or
/resources/guid/{guid}
or something else?
Short answer
You could use both /resource/{id} and /resource/{guid}. Many frameworks support regular expressions for matching path parameter values.
Long answer
REST is an architectural style and not a cookbook for designing URIs (see notes below). It doesn't enforce any URI design and it's totally up to you to pick the URIs that better identify your resources.
What you should keep in mind is: it's perfectly fine to have multiple mappings for the same entity. And each mapping is a resource, according to Fielding's dissertation:
A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.
With that being said, if you are supporting DELETE, it's important to mention how it's supposed to work:
4.3.5. DELETE
The DELETE method requests that the origin server remove the association between the target resource and its current functionality. In effect, this method is similar to the rm command in UNIX: it expresses a deletion operation on the URI mapping of the origin server rather than an expectation that the previously associated information be deleted. [...]
Note 1: The URI syntax is defined in the RFC 3986. As general rule, the path is organized in hierarchical form (with segments separated by /) and can contain non-hierarchical data in the query component (starting with ?).
Note 2: The REST architectural style is described in the chapter 5 of Roy T. Fielding's dissertation and it defines a set of constraints that must be followed by the applications that follow such architecture. However it says nothing about what the URIs must be like.
Note 3: The examples of a popular article written by Martin Fowler explaining a model defined by Leonard Richardson suggest a URI structure that looks friendly and easy to read.
I wouldn't normally duplicate an endpoint. The question would be:
why does one client have an id while another has a guid?
what design choice allowed that to happen?
I would leave it as a single resource endpoint:
GET
/resource/{id}
so clients who access resources via their id will use the above endpoint. I'd allow clients who access resources via their guid to exchange what they have (guid) for what they need (id):
GET
/id/{guid}
The above returns a resource id for the given resource guid. The client can then call the main resource endpoint with the id they have just received:
GET
/resource/{id}
but ultimately I'd look into why some clients use a guid rather than an id and change that so all clients access the API in the same way.
I am trying to design a REST API for a system where the resources are essentially identified by path-like addresses with varying numbers of segments. For example, a "Schema" resource could be represented on the file system as follows:
/Resources/Schemas/MyFolder2/MyFolder5/MySchema27
The file-system path /Resources/Schemas/ is the root folder for all Schemas, and everything below this is entirely user defined (as far as folder depth and folder naming). So, in the example above, the particular Schema would be uniquely identified by the following address (since "MySchema27" by itself would not necessarily be unique):
/MyFolder2/MyFolder5/MySchema27
What would be the best way to refer to a resource like this in a REST API?
If I have a /schemas collection my REST URL could be:
/schemas/MyFolder2/MyFolder5/MySchema27
Would that be a reasonable approach? Are there better ways of handling this?
I could, potentially, do a 2-step approach where the client would first have to search for a Schema using the Schema address (in URL parameters or in the request body), which would then return a unique ID that could then be used with a more traditional /schemas/{id} design. Not sure that I like that, though, especially since it would mean tracking a separate ID for each resource. Thoughts? Thanks.
The usual way to add a resource to your "folder" /Resources/Schemas/ is to make a POST request on it with the body of this POST request containing a representation of the resource to add, then the server will take care of finding the next free {id} and and setting the new resource to /Resources/Schemas/{id}.
Another approach is to, as you said, make a GET request on /Resources/Schemas/new which would return the next free {id}, and then, make a second request PUT directly on /Resources/Schemas/{id}. However this second approach is not as secure as the first since two simultaneous request could lead to the same new {id} returned and so the second PUT would erase the first. You can secure this with some sort of reservation mechanism.
This is called as Resource Based URI approach for building REST services . Follow these wonderful set of video tutorials to understand more about them and learn how to implement too . https://javabrains.io/courses/javaee_jaxrs
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?
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
In GCP / AWS, resource is used in reference to cloud infrastructure.
In general computing, a resource is a reference to a component with limited availability.
Dictionary
The definitions provide many more uses of the word.
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 nuance. It all depends on the context its used in.
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
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
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. 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
Consider a server which has the information of users, missions and their reward points.
Users and Reward Points are the resources
An end point can relate to more than one resource
Endpoints can be described using either a description or a full or
partial URL
Source: API Endpoints vs Resources
Which one of these URIs would be more 'fit' for receiving POSTs (adding product(s))? Are there any best practices available or is it just personal preference?
/product/ (singular)
or
/products/ (plural)
Currently we use /products/?query=blah for searching and /product/{productId}/ for GETs PUTs & DELETEs of a single product.
Since POST is an "append" operation, it might be more Englishy to POST to /products, as you'd be appending a new product to the existing list of products.
As long as you've standardized on something within your API, I think that's good enough.
Since REST APIs should be hypertext-driven, the URI is relatively inconsequential anyway. Clients should be pulling URIs from returned documents and using those in subsequent requests; typically applications and people aren't going to need to guess or visually interpret URIs, since the application will be explicitly instructing clients what resources and URIs are available.
Typically you use POST to create a resource when you don't know the identifier of the resource in advance, and PUT when you do. So you'd POST to /products, or PUT to /products/{new-id}.
With both of these you'll return 201 Created, and with the POST additionally return a Location header containing the URL of the newly created resource (assuming it was successfully created).
In RESTful design, there are a few patterns around creating new resources. The pattern that you choose largely depends on who is responsible for choosing the URL for the newly created resource.
If the client is responsible for choosing the URL, then the client should PUT to the URL for the resource. In contrast, if the server is responsible for the URL for the resource then the client should POST to a "factory" resource. Typically the factory resource is the parent resource of the resource being created and is usually a collection which is pluralized.
So, in your case I would recommend using /products
You POST or GET a single thing: a single PRODUCT.
Sometimes you GET with no specific product (or with query criteria). But you still say it in the singular.
You rarely work plural forms of names. If you have a collection (a Catalog of products), it's one Catalog.
I would only post to the singular /product. It's just too easy to mix up the two URL-s and get confused or make mistakes.
As many said, you can probably choose any style you like as long as you are consistent, however I'd like to point out some arguments on both sides; I'm personally biased towards singular
In favor of plural resource names:
simplicity of the URL scheme as you know the resource name is always at plural
many consider this convention similar to how databases tables are addressed and consider this an advantage
seems to be more widely adopted
In favor of singular resource names (this doesn't exclude plurals when working on multiple resources)
the URL scheme is more complex but you gain more expressivity
you always know when you are dealing with one or more resources based on the resource name, as opposed to check whether the resource has an additional Id path component
plural is sometimes harder for non-native speakers (when is not simply an "s")
the URL is longer
the "s" seems to be a redundant from a programmers' standpoint
is just awkward to consider the path parameter as a sub-resource of the collection as opposed to consider it for what it is: simply an ID of the resource it identifies
you can apply the filtering parameters only where they are needed (endpoint with plural resource name)
you could use the same url for all of them and use the MessageContext to determine what type of action the caller of the web service wanted to perform.
No language was specified but in Java you can do something like this.
WebServiceContext ws_ctx;
MessageContext ctx = ws_ctx.getMessageContext();
String action = (String)ctx.get(MessageContext.HTTP_REQUEST_METHOD);
if(action.equals("GET")
// do something
else if(action.equals("POST")
// do something
That way you can check the type of request that was sent to the web service and perform the appropriate action based upon the request method.