Working on a REST API with Play Framework.
I have a requirement to support a RESTful request containing the "order" with multiple "line items".
In terms of the "POST data", I see it like: (split into multi-lines for clarity)
OrderId=123&OrderType=regular&
ItemNum=1&ItemID=78&quantity=2&discount=20&
ItemNum=2&ItemID=70&quantity=1&
ItemNum=3&ItemID=75&quantity=1&discount=10
Note that I have an issue to require all the "line items" to come with a full set of data. In the example above, the 2nd item has no discount. Since I cannot "force" developers using the API to work with my own "wrapper", I want to leave some flexibility.
I would like to map it to something like:
method(int orderID, string orderType, Item[] items)
However, I failed to find something appropriate in the docs.
What's the right way?
Should I build my own parser of the HTTP request data?
Any alternative way to format the POST data - as long as it is ok with REST guidelines - is also acceptable.
Thanks
Max
To map an array of Pojo objects, then you need to put item. in front of the item object. Just like you map an object in a form. Then, you should specify that it is an array using the standard array syntax.
I would do something like the following
orderId=123&orderType=regular&
item[0].ItemNum=1&item[0].ItemID=78&item[0].quantity=2&item[0].discount=20&
item[1].ItemNum=2&item[1].ItemID=70&item[1].quantity=1&
item[2].ItemNum=3&item[2].ItemID=75&item[2].quantity=1&item[2].discount=10
Related
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.
I'm currently working on ng-admin.
I'm having a problem retrieving user data from my REST API (connected to a MongoDB) and displaying it.
I have identified the problem as the following:
When I enter http://localhost:3000/users into my browser, I get a list of all users in my database.
When I enter http://localhost:3000/users?_page=1&_perPage=30&_sortDir=DESC&_sortField=id,
I get [] as a result.
I am quite new to this, I used both my browser and the POSTMAN Chrome extension to test this and get the same result.
http://localhost:3000/users_end=30&_order=DESC&_sort=id&_start=0
This (/users_end) is a different request than /users.
It should be:
http://localhost:3000/users?end=30&_order=DESC&_sort=id&_start=0
Or, by looking at the other parameters:
http://localhost:3000/users?_end=30&_order=DESC&_sort=id&_start=0
with end or _end being the first parameter (mark the ?).
Update (it is ? and before the _, I have edited.):
If adding parameters to the request returns an empty list, try adding only one at a time to narrow down the problem (there's probably an error in the usage of those parameters - are you sure you need those underscores?).
Your REST API must have a way to handle pagination, sorting, and filtering. But ng-admin cannot determine exactly how, because REST is a style and not a standard. So ng-admin makes assumptions about how your API does that by default, that's why it adds these _end and _sort query parameters.
In order to transform these parameters into those that your API understands, you'll have to add an interceptor. This is all thoroughly explained in the ng-admin documentation: http://ng-admin-book.marmelab.com/doc/API-mapping.html
Let's say I have two controller methods: Users.preInsert and Users.insert. The preInsert method is the one used to display the user entry form (GET), while the insert method is responsible for the actual insertion (POST) or calling the 'insert' service.
This is how the routes looks like:
GET /users/add controllers.Users.preInsert(...)
POST /users/add controllers.Users.insert(...)
So how do I redirect a request (POST to GET) without losing the parameters like error messages returned from the insert service and the values inputed by the client so that they can be accessed and displayed in the entry form. The parameters may involve some complex objects. I have implemented it using the Caching API but I would like to know if there are any better ways of doing it.
That's the exact purpose of the Form objects (http://www.playframework.com/documentation/2.1.1/ScalaForms).
And I think there is a an error in your routes, it could look like:
GET /users/add controllers.Users.preInsert(...)
POST /users/add controllers.Users.insert(...)
You should definitively take a look at the form sample.
You don't need to redirect it back to the preInsert action, instead at the beginning of the insert check if form has errors and it it has display your view containing form (the same which you used in preInsert). It's described in the doc mentioned by nico_ekito in section Handling binding failure
Lets say I have a form with method=POST on my page.
Now this form has some basic form elements like textbox, checkbox, etc
It has action URL as http://example.com/someAction.do?param=value
I do understand that this is actually a contradictory thing to do, but my question is will it work in practice.
So my questions are;
Since the form method is POST and I have a querystring as well in my URL (?param=value)
Will it work correctly? i.e. will I be able to retrieve param=value on my receiving page (someAction.do)
Lets say I use Java/JSP to access the values on server side. So what is the way to get the values on server side ? Is the syntax same to access value of param=value as well as for the form elements like textbox/radio button/checkbox, etc ?
1) YES, you will have access to POST and GET variables since your request will contain both. So you can use $_GET["param_name"] and $_POST["param_name"] accordingly.
2) Using JSP you can use the following code for both:
<%= request.getParameter("param_name") %>
If you're using EL (JSP Expression Language), you can also get them in the following way:
${param.param_name}
EDIT: if the param_name is present in both the request QueryString and POST data, both of them will be returned as an array of values, the first one being the QueryString.
In such scenarios, getParameter("param_name) would return the first one of them (as explained here), however both of them can be read using the getParameterValues("param_name") method in the following way:
String[] values = request.getParameterValues("param_name");
For further info, read here.
Yes. You can retrieve these parameters in your action class.
Just you have to make property of same name (param in your case) with there getters and setters.
Sample Code
private String param;
{... getters and setters ...}
when you will do this, the parameters value (passed via URL) will get saved into the getters of that particular property. and through this, you can do whatever you want with that value.
The POST method just hide the submitted form data from the user. He/she can't see what data has been sent to the server, unless a special tool is used.
The GET method allows anybody to see what data it has. You can easily see the data from the URL (ex. By seeing the key-value pairs in the query string).
In other words it is up to you to show the (maybe unimportant) data to the user by using query string in the form action. For example in a data table filter. To keep the current pagination state, you can use domain.com/path.do?page=3 as an action. And you can hide the other data within the form components, like input, textarea, etc.
Both methods can be catched in the server with the same way. For example in Java, by using request.getParameter("page").
How to I represent a complex resource for a REST post?
Hello,
Currently I have an application which when the user hits "save" it iterates over all of the form elements and creates one mass object which manages a:
var = params = [{
attributes1: form1.getValues(),
attributes2: form2.getValues(),
.. ..
}];
I then send this mass object via a RPC POST to my "Entity" model service.
This entity which I wish to persist data for is quite complex. All in all, the data is spread accross about 30 tables. To help explain my actual question, the "entity" is a building (as in a physical property/house/apartment).
What I would like, is to be able to turn my mess into a RESTful API for saving properties.
The problem I have is that, saving details for a single model that spans a single table is fine. How do I structure my data object for transport when the model has
many to many relationships
one to many relationships
one to one relationships
For example:
Here is a WATERED down version of what I might have on a property and the sample data
propertyId: 1,
locationId: 231234,
propertyName: "Brentwood",
kitchenFeatures: [
{ featureId: 1, details: "Induction hob"},
{ featureId:23, details: "900W microwave"}
],
propertyThemes: [ 12,32,54,65 ]
This actually goes on a lot more.. but you can get the general gist. kitchenFeatures would be an example of a many-to-many, where I have a featuresTable which has all of the features like so:
`featureId`, `feature`
1 "Oven Hob"
23 "Microwave"
and propertyThemes would be an example of another many-to-many.
How am I expected to form my "object" to my RESTful service? Is this even possible?
ie. If I want to save this property I would send it to:
http://example.com/api/property/1
The approach I would use here is hypermedia and links:
/property
/property/{id}
/property/{id}/features/{id}
Depending on your domain you might even get away with:
/property/{id}/features/{name}
or
/property/{id}/features/byname/{name}
Thus you can do REST operations and serve JSON or XHTML hypermedia.
Property details:
Request: GET /property/1
Response:
{
..
"name": "Brentwood",
"features": "/property/1/features"
..
}
Brentwood's features:
GET /property/1/features
{
..
"Kitchen": "/property/1/features/1",
"Dog Room": "/property/1/features/dog%20room",
..
}
GET /property/1/features/1
{
..
"Induction hob": "/property/1/features/1/1",
"900W microwave": "/property/1/features/1/23",
"nav-next" : "/property/1/features/dog%20room",
..
}
To add a relation you can do something like this:
POST /property/1/features
{
..
"Name": "Oven Hob"
..
}
If you know what the relation will be you use a PUT:
PUT /property/1/features/23
{
..
"Name": "Oven Hob"
..
}
You can serve multiple media types:
GET http://host/property/1/features/dog%20room.json
GET http://host/property/1/features/dog%20room.xhtml
For the response in xhtml the response can use named links like this:
..
Kitchen
..
There are other aspects of REST that you can use such as response code which I did not include above.
Thus, to model relations you make use of links which can be in itself a resource that can be operated on with GET, PUT, POST and DELETE or even custom verbs such as ASSOCIATE or LINK. But the first four are the ones that people are used to. Remember PUT is idempotent but not POST. See PUT vs POST in REST
Edit: You can group your links into JSON arrays to give structure to your hypermedia.
I think you're really asking, "How do I represent complex data in a form suitable for transmission within a POST?", right? It's less to do with REST and more to do with your choice of media type. I would suggest starting with a pure JSON representation, using arrays and cross-referenced ID fields to map the relationships. You could also do this with XML, of course.
The examples you gave look right on the money. You just need to ensure that both parties (browser and server) agree on the structure and interpretation of the media type you use.
I'm dealing with the exact same thing. I opted to not use id's anywhere, but use urls everywhere an id would normally be expected.
So in your case, the kitchenfeatures could simply be an array with urls to:
/feature/1
/feature/23
And the themes to
/propertyTheme/12
/propertyTheme/32
etc..
In the case of many-to-many relationships, we update all the relations as a whole. Usually we simply dump the existing data, and insert the new relationships.
For one to many relationships we sometimes extend the urls a bit where this makes sense. If you were to have comments functionality on a 'property', this could look like
/property/1/comment/5
But this really depends on the situation for us, for other cases we put it in the top-level namespace.
Is this helpful to you?