I want to expose some portion of my big REST resource as another resource (sub-resource). Is it valid to do so? What problems are possible with this approach? Is there a better way?
For example, I have a collection of computers. Each computer in this collection (main resource) have it's own sub-parts (sub-resources).
/api/computers/117/chassis
/api/computers/117/motherboard
/api/computers/117/cpu
Where computers is the collection and chassis, motherboard and cpu are sub-resources of computer #117.
Yes it is. You can have problems when you want to access only resources like a specific type of CPU, but it's okay if you have also /api/cpus/123
Related
My application provides the following resource:
GET /user/:id/orders
As commonly used, this returns a list of all the user's orders.
Now, a client wants to check if a user has any orders at all without actually getting the complete list.
My current approach looks like this:
GET /user/:id/orders/exist
But it looks kind of odd to me.
Is there a more "standard" way of designing this? In the end, this resource only needs to return the information:
yes, user has orders
no, user doesn't have any orders
What you will see in some API is the notion of a resource that exists (204) or does not exist (404).
But I really don't recommend that: saving a few bytes in your representation of the resource doesn't help very much when you are already sending a response-line and a bunch of HTTP headers.
Your "resource model" can be anything you want.
The REST interface is designed to be efficient for large-grain hypermedia data transfer, optimizing for the common case of the Web, but resulting in an interface that is not optimal for other forms of architectural interaction -- Fielding, 2000
So you can create fine grained resources if you like; but there are can be consequences to that. "Tradeoffs" are a thing.
Resources are generalizations of "documents"; if it makes sense to have a report that is just a count of the number of orders, or a statement that the number of orders is greater than zero, or whatever, then that report can certainly be a resource in your resource model.
If you know what the report is, then you might be able to guess at a name for the report, and from there to a spelling for it.
There's no particular reason that the report identifier has to be part of the /user hierarchy; the machines don't care what spelling conventions you use.
/user/:id/orders/report
/user/:id/orders-report
/user/:id/report
/report/:id
/report?user=:id
/report/user=:id
Those are all fine; choose whichever variation is appropriate to your local conventions.
Note that you want to be aware of caching - when you have information in two different resources, it is easy for the client's locally cached copies to contradict each other (report says that there are orders, but the orders list is empty; or the other way around). As far as REST, and general purpose components are concerned, different resources are different, and vary independently of each other.
In the large grained world, you don't have that problem so often, because you throw the kitchen sink into a single resource; as long as its produced representations are internally consistent, the cached copies will be as well.
Using HTTP POST method/AnyMethod If a client is sending some information like name, number etc in a representation to server and server is storing it to DB then here name and number is called a resource?
or we are creating a resource in server with the information what client gave?
then client will not have a resource at any time?
Let's take a theoretical look at this:
resource = the intended conceptual target of a hypertext reference
[...]
The key abstraction of information in REST is a resource. Any
information that can be named can be a resource: a document or image,
a temporal service (e.g. "today's weather in Los Angeles"), a
collection of other resources, a non-virtual object (e.g. a person),
and so on. In other words, any concept that might be the target of an
author's hypertext reference must fit within the definition of a
resource. 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.
Source: Fielding, Roy Thomas. Architectural Styles and the Design of Network-based Software Architectures. Doctoral dissertation, University of California, Irvine, 2000 as referenced in RFC 7231.
In a brief interpretation that means that the resource is never any particular data but rather a mapping. Let's put it into something tangible:
GET /members
-> A resource called members (= set of entities) consisting out of username, e-mail address.
Members is considered a resource because it describes what the set of entities represent and because I've decided so.
To answer your questions:
> name and number is called a resource?
Depends on the context. Are you storing the name and number alone and independent from each other? Then they are resources, if they are part of something else, the resource would be the thing the two values describe (e.g. contact information).
Since the concept is abstract, you may even define three resources here: names, contact information and numbers. As it said, any information can be a resource, but that's not a must. So you are free to decide what you call a resource and what not.
> or we are creating a resource in server with the information what
> client gave?
No. We are creating an entity within a resource. The resource was defined by you earlier.
> then client will not have a resource at any time?
To be frank, I am sitting over this question for quite some time now - the dissertation doesn't state something specific but from interpreting and understanding the abstract concept, I'd say no. The server always holds the state of a resource, the client just gets or modifies it, but never provides any resource itself.
Related Questions:
What are REST resources?
What is the difference between resource and resource representation in REST?
I have this API : GET /travels/generate/{city-departure}/{city-arrival}
It generate a list of possible travels path (with train changes, etc).
Now these are not real resources because they don't have ID (they are only generated for proposal).
What is the best way to select one and save it in a RESTful way ? Should I create a temporary resource for each proposal like "GET /temporary-travel/{id}" ?
A REST resource does not need to have an ID. It must be identifiable. Your URLs
/travels/generate/{city-departure}/{city-arrival}
are completely OK to identify a resource.
A REST resource does not need to have an ID. It must be identifiable.
One solution would be using a list index (e.g. GET /travels/generate/{city-departure}/{city-arrival}/{index} ). This somehow needs you to remember the content and the order of the proposed travel paths.
To overcome the limitation of temporary storing possible travel paths, you may either store them permanently and providing them an static identifier or you may provide a domain specific key that consists of multiple chained static identifiers that provide an identity to your travel path (e.g. chaining all route segment IDs or so).
I somehow prefer the idea of storing all possible travel paths even knowing it is technically somewhat nearly impossible. I like it because the travel paths possibly provided by your system are kind of limited due to the algorithm and the data base you use.
The task: I have multiple resources that need to be updated in one HTTP call.
The resource type, field and value to update are the same for all resources.
Example: have set of cars by their IDs, need to update "status" of all cars to "sold".
Classic RESTFul approach: use request URL something like
PUT /cars
with JSON body like
[{id:1,status:sold},{id:2,status:sold},...]
However this seems to be an overkill: too many times to put status:sold
Looking for a RESTful way (I mean the way that is as close to "standard" rest protocol as possible) to send status:sold just once for all cars along with the list of car IDs to update. This is what I would do:
PUT /cars
With JSON
{ids=[1,2,...],status:sold} but I am not sure if this is truly RESTful approach.
Any ideas?
Also as an added benefit: I would like to be able to avoid JSON for small number of cars by simply setting up a URL with parameters something like this:
PUT /cars?ids=1,2,3&status=sold
Is this RESTful enough?
An even simpler way would just be:
{sold:[1,2,...]}
There's no need to have multiple methods for larger or smaller numbers of requests - it wastes development time and has no noteable impact upon performance or bandwidth.
As far as it being RESTful goes, as long as it's easily decipherable by the recipient and contains all the information you need, then there's no problem with it.
As I understand it using put is not sufficient to write a single property of a resource. One idea is to simply expose the property as a resource itself:
Therefore: PUT /car/carId/status with body content 'Sold'.
Updating more than one car should result in multiple puts since a request should only target a single resource.
Another Idea is to expose a certain protocol where you build a 'batch' resource.
POST /daily-deals-report/ body content {"sold" : [1, 2, 3, 4, 5]}
Then the system can simply acknowledge the deals being made and update the cars status itself. This way you create a whole new point of view and enable a more REST like api then you actually intended.
Also you should think about exposing a resource listing all cars that are available and therefore are ready for being sold (therefore not sold, and not needing repairs or are not rent).
GET /cars/pricelist?city=* -> List of all cars ready to be sold including car id and price.
This way a car do not have a status regarding who is owning the car. A resource is usually independent of its owner (owner is aggregating cars not a composite of it).
Whenever you have difficulties to map an operation to a resource your model tend to be flawed by object oriented thinking. With resources many relations (parent property) and status properties tend to be misplaced since designing resources is even more abstract than thinking in services.
If you need to manipulate many similar objects you need to identify the business process that triggers those changes and expose this process by a single resource describing its input (just like the daily deals report).
Your triplestore contains a lot of nodes, and you have to make accessible this database via a REST interface.
Now, my solution would be that every named (not-anonymous) node is exported as a resource, whose representation is:
all the triples having the node as a subject
all the triples having the node as an object
all the connected anonymous nodes.
I am a little reluctant on point number 2: this would basically give both incoming and outgoing triples.
What is your take on a REST sytle representation of a purely RDF-oriented data store ?
Do you share my point of view or not, and if not, what is your take on it ?
Depends on what the the data is and what the interface users want to do with it. This question is similar to what the SPARQL DESCRIBE query form should return. (It's determined by the implementation.)
For the use cases I've had with RDF data, I'd go with 1 and 3, producing a blank node closure of the resource. Additionally, you could have a separate interface for case 2, returning the incoming arcs of the resource.
One easy way to make an RDF dataset REST traversible is to use URLs for all traversible elements.
When the URL is accessed, for example via HTTP GET, then result shows the connected nodes (connected as properties and/or inverse properties).
More formally the returned representation could be a Concise Bounded Description of the resource.
(disclaimer: this may not correspond exactly to the content of your question, but it corresponds to the title)
I think that about the topic of Rest representation of RDF data is a general problem of inverting the order of concepts. For me the normal would be to have a collection of Rest documents with RDF data and use a RDF database for indexing and making global querys.
In this situation you can organize your resources in the way you prefer.
Also (if you pretend to use the URI of the node as the exported resource) your approach will have subtle problems about what is the meaning of your resources: the Rest resources you propose here are "information resources" and then they cannot be abstract resources. There will be a conflict between information and meta-information.
I published an article here explaining this view in more detail.