Our API's entry point has a rel named "x:reports" (where x is a prefix defined in the HAL representation, by way of a curie - but that's not important right now).
There are several types of reports. Following "x:report" provides a set of these affordances, each with a rel of its own - one rel is named "x:proofofplay". There is a set of lookup values associated with this type of report (and only this type of report). The representation returned by following "x:proofofplay" has a rel to this set of values "x:artwork".
This results in the following hierarchy
reports
proofofplay
artwork
While the "x:artwork" resource is fairly small, it does take some time to fetch it (10 sec). So the client has opted to async load it at app launch.
In order to get the "x:artwork"'s href the client has to follow the links. I'm not sure whether this is a problem. It seems potentially unRESTful, as the client is depending on out-of-band knowledge of the path to this resource. If ever path to artwork changes (highly unlikely) the client will break (though the hrefs themselves can change with impunity).
To see why I'm concerned, the launch function looks like this:
launch: function () {
var me = this;
Rest.getLinksFromEntryPoint(function(links) {
Rest.getLinksFromHref(links["x:reports"].href, function(reportLinks){
Rest.getLinksFromHref(reportLinks["x:proofofplay"].href, function(popLinks){
me.loadArtworks(popLinks["x:artwork"].href);
});
});
});
}
This hard-coding of the path simultaneously makes me think "that's fine - it's based on a published resource model" and "I bet Roy Fielding will be mad at me".
Is this fine, or is there a better way for a client to safely navigate such a hierarchy?
The HAL answer to this is to embed the resources.
Depending a bit on your server-side technology, this should be good enough in your case because you need all the data to be there before the start of the application, and since you worry about doing this sequentially, you might parallelize this on the server.
Your HAL client should ideally treat things in _links and things in _embedded as the same type of thing, with the exception that in the second case, you are also per-populating the HTTP cache for the resources.
Our js-based client does something like this:
var client = new Client(bookMarkUrl);
var resource = await client
.follow('x:reports')
.follow('x:proofofplay')
.follow('x:artwork')
.get();
If any of these intermediate links are specified in _links, we'll follow the links and do GET requests on demand, but if any appeared in _embedded, the request is skipped and the local cache is used. This has the benefit that in the future we can add new things from _links to _embedded, and speeding up clients who don't have to be aware of this change. It's all seamless.
In the future we intend to switch from HAL's _embedded to use HTTP2 Push instead.
Related
I am struggling to come with proper REST URL for converting one resource into another. The API method does not do any CRUD operations but instead transform/convert one resource into another type of resource.
I have 2 resources Workunit and Document. I have 3 operations on these two resources
1> trasform Workunit into Document
2> sync Workunit into Document (different logic than transform)
3> transform Document into Workunit
and i have the following urls
[POST] api/v1/workunits/transform
[POST] api/v1/workunits/sync
[POST] api/v1/documents/transform
problem here is action is a part of REST URL
any suggestions?
problem here is action is a part of REST URL
That's not a problem - clients don't depend on the URL for semantics, so you can use any spelling you like; api/v1/4dc233fa-c77c-49d7-b7d6-296ffeb89612 is perfectly satisfactory.
It's analogous to having a verb as a variable name -- it may not be in keeping with your local coding standards, but the compiler doesn't care. So too is it with your URL and the general purpose components that use it.
Choosing a good identifier is like choosing a good name; it requires having a clear understanding of what the thing is. In the case of URI/URL, the thing being identified is a resource, which is to say something that is described by a document. GET/POST/PUT/DELETE and so on are all requests that we do something interesting with the underlying document.
So the usual pattern might be to POST a transform message to the workunit resource, or to POST a transform message to the Document resource, or to POST a sync message to the workunit resource.
Hmm, that last one sounds backwards; if the workunit is unchanged, and the Document is changed by the sync, then you would probably send a sync message to the Document resource.
So if I have /api/v1/documents/1, and I need to sync it, then I would normally use POST /api/v1/documents/1, with the sync semantics described in the message body (on the web, that would usually be an application/x-www-form-urlencoded representation of the sync message).
But it could just as easily be a message that says "Sync documents/1 with workitem/2" that I POST to the todo list for the synchronizer.
We are just putting documents politely into the server's in-tray, so that it can do useful work. The in-tray can have whatever label you want.
It is fine with given situation.
Nevertheless, if I am getting you right it may be a good idea to create two different controllers.
It's up to you but think of changing structure a little bit:
Separate the logic of Transformation and Sync into two different controllers, so you can avoid URL issue.
TransformationController
[Route("api/v1/transformation-controller/")]
TransformationController : ControllerBase
{
[HttpPost("workunits")]
public Task<Response> TransformWorkunits()
{
//logic
}
[HttpPost("documents")]
public Task<Response> TransformDocuments()
{
//logic
}
}
SynchronizationController
[Route("api/v1/synchronization-controller/")]
TransformationController : ControllerBase
{
[HttpPost("workunits")]
public Task<Response> SyncWorkunits()
{
//logic
}
}
So the URLs will be:
[POST] api/v1/transformation-controller/workunits
[POST] api/v1/synchronization-controller/workunits
[POST] api/v1/transformation-controller/documents
So this is a way to avoid verbs and fit REST rules.
If there will be more objects to transform/sync from and into, then you'll have to improve this approach.
We are currently trying to come up with a set of REST API that would fit our resource models.
A simplified example of the resource is:
CompanyInfo: {
totalNumberOfEmployees: Number,
employees: [...employees],
}
Employee: {
name: String,
}
In this case, "CompanyInfo" is like a virtual resource that does not exist in DB. It is a short cut for getting all the data related to the Company resource. The idea was to reduce the amount of logic on FE and create more convenient endpoint instead.
Our current endpoint design is:
GET /api/companyInfos/{companyId}/employees
GET,POST,PUT,DELETE /api/companyInfos/{companyId}/employees/{employeeId}
The reason for the extra {companyId} is because these endpoint does not return "Employees", it instead return a "CompanyInfo" that contains "Employees" embedded in the payload.
This is to avoid the aggregated property "totalNumberOfEmployees" not being updated in case sync when we call POST to create a new "Employee"
So my questions are:
Is this the correct approach to the problem of "too many requests" or "too much logic in FE"?
Is it acceptable for the endpoint to return a completely different resource than what its url describe?
Thanks a lot :)
For your Fist question
Is this the correct approach to the problem of "too many requests" or "too much logic in FE"?
yes Sometimes this is how it is suppose to be done. when data sent is small in each request. to many request does not affect the performance so This is how it is suppose to be done .
And Generally it is recommended to write one monolithic Ajax call in front end which will be capable of making any kind of call , By taking callback as parameter, and method , arguments as parameters .
So it will not be to much of logic if you follow this approach . All you have to write is callback for each of Ajax call . How ever sometimes situation may not allow for this Example:if you are using content-type like 'multipart/mixed'
there you have to write another ajax call code
However nowdays most front end has too much of logic based on how interactive website is . So your primary concern should be about look of web site .
For you second question
Is it acceptable for the endpoint to return a completely different resource than what its url describe?
yes . It is acceptable . but it is recommended that client mention all the MIME types which it expects in Accept header and Only those MIME types should be returned by Api.
I am currently programming a REST service and a website that mostly uses this REST service.
Model:
public class User {
private String realname;
private String username;
private String emailAddress;
private String password;
private Role role;
..
}
View:
One form to update
realname
email address
username
Another form to update the role
And a third form to change the password
.
Focussing on the first view, which pattern would be a good practice?
PUT /user/{userId}
imho not because the form contains only partial data (not role, not password). So it cannot send a whole user object.
PATCH /user/{userId}
may be ok. Is a good way to implement it like:
1) read current user entity
2)
if(source.getRealname() != null) // Check if field was set (partial update)
dest.setRealname(source.getRealname());
.. for all available fields
3) save dest
POST /user/{userId}/generalInformation
as summary for realname, email, username
.
Thank you!
One problem with this approach is that user cannot nullify optional fields since code is not applying the value if (input is empty and value) is null.
This might be ok for password or other required entity field but for example if you have an optional Note field then the user cannot "clean" the field.
Also, if you are using a plain FORM you cannot use PATCH method, only GET or POST.
If you are using Ajax you might be interested in JSON Merge Patch (easier) and/or JavaScript Object Notation (JSON) Patch (most complete); for an overview of the problems that one can find in partial updates and in using PATCH see also this page.
A point is that a form can only send empty or filled value, while a JSON object property can have three states: value (update), null (set null) and no-property (ignore).
An implementation I used with success is ZJSONPATCH
Focussing on the first view, which pattern would be a good practice?
My suggestion starts from a simple idea: how would you do this as web pages in HTML?
You probably start from a page that offers a view of the user, with hyperlinks like "Update profile", "Update role", "Change password". Clicking on update profile would load an html form, maybe with a bunch of default values already filled in. The operator would make changes, then submit the form, which would send a message to an endpoint that knows how to decode the message body and update the model.
The first two steps are "safe" -- the operator isn't proposing any changes. In the last step, the operator is proposing a change, so safe methods would not be appropriate.
HTML, as a hypermedia format, is limited to two methods (GET, POST), so we might see the browser do something like
GET /user/:id
GET /forms/updateGeneralInformation?:id
POST /updates/generalInformation/:id
There are lots of different spellings you can use, depending on how to prefer to organize your resources. The browser doesn't care, because it's just following links.
You have that same flexibility in your API. The first trick in the kit should always be "can I solve this with a new resource?".
Ian S Robinson observed: specialization and innovation depend on an open set. If you restrict yourself to a closed vocabulary of HTTP methods, then the open set you need to innovate needs to lie elsewhere: the RESTful approach is to use an open set of resources.
Update of a profile really does sound like an operation that should be idempotent, so you'd like to use PUT if you can. Is there anything wrong with:
GET /user/:id/generalInformation
PUT /user/:id/generalInformation
It's a write, it's idempotent, it's a complete replacement of the generalInformation resource, so the HTTP spec is happy.
Yes, changing the current representation of multiple resources with a single request is valid HTTP. In fact, this is one of the approaches described by RFC 7231
Partial content updates are possible by targeting a separately identified resource with state that overlaps a portion of the larger resource
If you don't like supporting multiple views of a resource and supporting PUT on each, you can apply the same heuristic ("add more resources") by introducing a command queue to handle changes to the underlying model.
GET /user/:id/generalInformation
PUT /changeRequests/:uuid
Up to you whether you want to represent all change requests as entries in the same collection, or having specialized collections of change requests for subsets of operations. Tomato, tomahto.
So nothing new here I am just trying to get some clarification and cannot seem to find any in other posts.
I am creating a new resource restulfully, say:
/books (POST)
with a body:
{
title: 'The Lion, the Witch and the Wardrobe',
author: 'C. S. Lewis'
}
I know that I should return a 201 (Created) with a Location header of the new resource:
Location: /books/12345
The question I cannot seem to answer for myself is what should the server return in the body.
I have often done this type of response:
{
id: 12345,
title: 'The Lion, the Witch and the Wardrobe',
author: 'C. S. Lewis'
}
I have done this for a couple reasons:
I have written api for front end frameworks like angularjs. In my
particular case I am using angular resources and I often need just
the id for the resource to locate it. If I did not return the id in
the response body I would need to parse it out of the Location
header.
In a GET of all books I usually return the entire object not just
the id. In this sense my client code does not have to differentiate
where to get the id from (location header or body).
Now I know I am really in the grey area here, but most people are saying that returning the entire resource is 'bad' practice. But what if the server changes/adds information to the resource. It definitely adds the id, but might also add other things like a timestamp. In the case that I do not return the entire resource, is it really better to do a POST, return the id, then have the client perform a GET to get the new resource.
Returning the new object fits with the REST principle of "Uniform Interface - Manipulation of resources through representations." The complete object is the representation of the new state of the object that was created.
There is a really excellent reference for API design, here: Best Practices for Designing a Pragmatic RESTful API
It includes an answer to your question here: Updates & creation should return a resource representation
It says:
To prevent an API consumer from having to hit the API again for an
updated representation, have the API return the updated (or created)
representation as part of the response.
Seems nicely pragmatic to me and it fits in with that REST principle I mentioned above.
Returning the whole object on an update would not seem very relevant, but I can hardly see why returning the whole object when it is created would be a bad practice in a normal use case. This would be useful at least to get the ID easily and to get the timestamps when relevant.
This is actually the default behavior got when scaffolding with Rails.
I really do not see any advantage to returning only the ID and doing a GET request after, to get the data you could have got with your initial POST.
Anyway as long as your API is consistent I think that you should choose the pattern that fits your needs the best. There is not any correct way of how to build a REST API, imo.
After a post I like to return something like this:
Response
.created(URI("/obj/$id"))
.entity(TheNewObj())
.build()
Status 201 - CREATED
Header Location - the location of the new object
Entity - the new object
I'm trying to figure out how to best lay out a set of Restlet APIs.
I have a User entity, which might have the standard CRUD operations, which fits nicely into rest, but there are other ones too like "reset password", or "terminate".
What is the best way to lay this out?
Here is what i was thinking:
/1.0/user/update //perhaps this would just be a PUT on /1.0/user
/1.0/user/resetPassword //This would reset the password, but also send an email.
/1.0/user/terminate //This might do some additional cleanup
Then I would make a UserResource that would really attach like this
/1.0/user/{actionType}
And the handling code might look like this (psuedo):
action = request.getAttributes().get("actionType");
if (action == "update") {
do update
} elif (action == "resetpassword") {
do resetpassword
} elif (action == "terminate") {
do terminate
}
Really bad idea? Really ninja idea?
I think it's an OK idea. If you want your application to be RESTful, you really have to provide links in the representation for your User resource, and document them as URIs that perform the selected actions.
The Sun Cloud API does just this:
GET a VM returns a representation VM including "controllers" that are URIs that perform functions (see description of the VM media type)
Client knows about the media type, recognizes controllers (e.g. a VM provides "start", "stop" etc.
URI of control resource for that particular VM is right there
So as you can see, if you use /1.0/user/resetPassword or /1.0/user?op=resetPassword or /1.0/resetPassword?userId=xyzzy is a bit irrelevant, since the client really shouldn't care, it merely follows links in representations.
Also, remember to use POST for such operations since they are generally not idempotent and they probably have side effects.
How about these?
PUT /user/bob
DELETE /user/bob/password
DELETE /user/bob
and don't forget mogsie's point that the client should discover these URLs from some other document, it should not know them in advance.