I'll try to make it simple, because I can't find a tutorial with this problem, I think it belongs to best practices designing REST APIs.
I have two entities
- Role (id, name)
- User (id, name, Role, etc.)
When making a POST Request to some controller what is the best approach to do it, in a json way.
{
"id": 1,
"name": "Luis",
"rol":{
"id": 1,
"name":Administrator,
"users" : [
//I think this is for the bidirectional relationship so
can I avoid this property as well??
]
},
"another" : bla bla bla
}
For this approach do I have to put all the properties of the entity that is related?? Meaning that i have to create a json with this structure, or can ommit properties, here a question get out of my head How Spring knows this is an entity so it can make a Role object and hence a relationship to User?
Or do I have to post like this:
{
"id": 1,
"name": "Luis",
"role_id" : 1,
"another" : bla bla bla
}
So when the controller knwos about this, first it will find a Role by using, lets say Role.findById() of course I use a service layer... and then attach it to the user.
What is the best approach for this?
Thank you.
In my opinion this question is particularly interesting because it recalls a very common developers' pitfall i.e. understanding the borders between design and implementation.
First, let's point out a very important concept: your API is decoupled from your business object. Your API could be designed by an architect who knows nothing about Java or Spring and cares even less of your User or Role classes.
In REST, servers and clients exchange resources representations and this means that the server is free to determine the most meaningful representation for that resource. In other words, whether you are using JSON, XML or whatever, you are not forced to include in your API some information just because it's present in some form in your backing object.
Resources exposed in your API live in another dimension. They are agnostic with respect of the Spring controller.
So, the answer to your question is: send the information that is meaningful for that operation. The server knows the rest.
I have to admit that your second question "How Spring knows this is an entity so it can make a Role object and hence a relationship to User?" sounds a little weird to me. Spring Controllers bind HTTP requests to class methods. Those methods are like the following
#RequestMapping(value = "/users", method = RequestMethod.POST)
public String createUser(#RequestBody UserModel user) {
//...
}
so when you fire the POST to the right URL the request will be dispatched from the AS to your DispatcherServlet and finally to your Controller and createUser method. The payload, i.e. the JSON representation, is now unmarshalled into a UserModel class defined accordingly to your user representation (for example including id, name and roleId). At this point you are in control of everything since you have your user available for performing all the operations you need. Probably you will create a Role object and a User object, fulfill the dependencies between the two classes, calling your DAO or whathever, wait for the persistence layer to complete its operation and return your 201 created HTTP status to the client (with the location header filled, if you want to be RESTful).
Related
Which annotate the relationship allow Jackson to better handle the relation, for save Click ? How change request:
{ "idBanner": 2, "fullnameClient": "Maria"}
#JsonManagedReference, #JsonBackReference,#JsonIdentityInfo,#JsonIgnore...
Working format-request (save Click):
#RequestParam is used to map just request parameters. For example, it will work for requests like POST /sentemail?fullnameClient=vov&idBanner=1
To get request body you should use #RequestBody annotation.
Important notice
I would recommended don't use models (entities) for requests and responses, because it increases a coupling between your business logic and external contract Rest API. For example, in future you will not able to change model without changing of external contract and vise versa.
But if you still want to use entities as request/response body, I would recommend taking a look on Jackson MixIns. It helps to have separate mapping for Jackson and Entities.
I'm new to Spring development and am currently looking for best practices for creating objects based on JSON data passed to a rest service, which are then to be stored using JPA.
As an example, let's assume a simplified file upload service where clients can post the following JSON object to:
{"filename":"myfile.pdf", "data":someByteArray, "extension":"pdf"}
On the server, I don't want to store the file's raw data in the database, but upload it to some cloud storage and just store a link to it. So once the "data" parameter content is stored and the link is received, it is obsolete.
The options I've come up with is:
a) define one 'union' class to deserialize the request body that comprises all fields ("filename", "link", "extension" AND "data"), marking 'intermediate' data as #Transient, so it won't be stored in the database,
b) define two classes: one solely for deserializing the request body ("filename", "data", "extension") which is then used to construct the desired entity class ("filename", "link", "extension") that is to be stored,
c) define a custom JsonDeserializer that parses the request body and constructs the entity class ("filename", "link", "extension").
While all of the approaches will probably work, in a more complex scenario, option a) will clutter the entity's class with members that are only required for deserializing once, while option b) and c) may result in a lot of additional classes.
Is there any best practice for this? Btw, thanks for reading this far :)
I have an ASP.NET Web API project, and I want to use oData filters in the project, with the ASP.NET oData preview package. This means I need to use IQueryable as the response type.
Unfortunately, the consumer requires the response wrapped like so:
{
"total": 2,
"success": true,
"data": [
{ object1 },
{ object2 } ]
}
I created a wrapper object which assigns the IQueryable response from my original version to the "data" property, and sets the values for the "total" and "success" properties as well. This creates the JSON response the consumer is looking for. But it's no longer IQueryable, which means I can't implement oData filters.
I was hoping to take my wrapper object and make it implement IQueryable by setting its enumerators, etc. However, I don't think this will work because I have to assign the Provider and Expression properties to implement the interface, and I don't know what I should put there. I'm using a Repository pattern with IoC, and the EntityFramework Code First data access is in a separate project, with concrete objects assigned to the interface placeholders using Ninject. Perhaps I can abstract out the interfaces all the way from the data access layer so that the the Repository objects carry a reference to an IQueryProvider. Do you think this would work, and allow it to support the automated oData integration?
Here's how you do it. Behind the scenes, [Queryable] just creates an instance of ODataQueryOptions and then applies it to the queryable you return. The good news is that you can parameter bind ODataQueryOptions and have code that looks like this:
public Wrapper<MyObject> Get(ODataQueryOptions<MyObject> queryOptions)
{
IQueryable<MyObject> queryResults = queryOptions.ApplyTo(dbSet);
return Wrap(queryResults);
}
You don't even need [Queryable] anymore because you're doing what it would have done for you. Hope that helps.
I have a collection resource called Columns. A GET with Accept: application/json can't directly return a collection, so my representation needs to nest it in a property:-
{ "propertyName": [
{ "Id": "Column1", "Description": "Description 1" },
{ "Id": "Column2", "Description": "Description 2" }
]
}
Questions:
what is the best name to use for the identifier propertyName above? should it be:
d (i.e. is d an established convention or is it specific to some particular frameworks (MS WCF and MS ASP.NET AJAX ?)
results (i.e. is results an established convention or is it specific to some particular specifications (MS OData)?)
Columns (i.e. the top level property should have a clear name and it helps to disambiguate my usage of generic application/json as the Media Type)
NB I feel pretty comfortable that there should be something wrapping it, and as pointed out by #tuespetre, XML or any other representation would force you to wrap it to some degree anyway
when PUTting the content back, should the same wrapping in said property be retained [given that it's not actually necessary for security reasons and perhaps conventional JSON usage idioms might be to drop such nesting for PUT and POST given that they're not necessary to guard against scripting attacks] ?
my gut tells me it should be symmetric as for every other representation but there may be prior art for dropping the d/*results** [assuming that's the answer to part 1]*
... Or should a PUT-back (or POST) drop the need for a wrapping property and just go with:-
[
{ "Id": "Column1", "Description": "Description 1" },
{ "Id": "Column2", "Description": "Description 2" }
]
Where would any root-level metadata go if one wished to add that?
How/would a person crafting a POST Just Know that it needs to be symmetric?
EDIT: I'm specifically interested in an answer that with a reasoned rationale that specifically takes into account the impacts on client usage with JSON. For example, HAL takes care to define a binding that makes sense for both target representations.
EDIT 2: Not accepted yet, why? The answers so far don't have citations or anything that makes them stand out over me doing a search and picking something out of the top 20 hits that seem reasonable. Am I just too picky? I guess I am (or more likely I just can't ask questions properly :D). Its a bit mad that a week and 3 days even with an )admittedly measly) bonus on still only gets 123 views (from which 3 answers ain't bad)
Updated Answer
Addressing your questions (as opposed than going off on a bit of a tangent in my original answer :D), here's my opinions:
1) My main opinion on this is that I dislike d. As a client consuming the API I would find it confusing. What does it even stand for anyway? data?
The other options look good. Columns is nice because it mirrors back to the user what they requested.
If you are doing pagination, then another option might be something like page or slice as it makes it clear to the client, that they are not receiving the entire contents of the collection.
{
"offset": 0,
"limit": 100,
"page" : [
...
]
}
2) TBH, I don't think it makes that much difference which way you go for this, however if it was me, I probably wouldn't bother sending back the envelope, as I don't think there is any need (see below) and why make the request structure any more complicated than it needs to be?
I think POSTing back the envelope would be odd. POST should let you add items into the collection, so why would the client need to post the envelope to do this?
PUTing the envelope back could make sense from a RESTful standpoint as it could be seen as updating metadata associated with the collection as a whole. I think it is worth thinking about the sort of meta data you will be exposing in the envelope. All the stuff I think would fit well in this envelope (like pagination, aggregations, search facets and similar meta data) is all read only, so it doesn't make sense for the client to send this back to the server. If you find yourself with a lot of data in the envelope that the client is able to mutate - then it could be a sign to break that data out into a separate resource with the list as a sub collection. Rubbish example:
/animals
{
"farmName": "farm",
"paging": {},
"animals": [
...
]
}
Could be broken up into:
/farm/1
{
"id": 1,
"farmName": "farm"
}
and
/farm/1/animals
{
"paging": {},
"animals": [
...
]
}
Note: Even with this split, you could still return both combined as a single response using something like Facebook's or LinkedIn's field expansion syntax. E.g. http://example.com/api/farm/1?field=animals.offset(0).limit(10)
In response, to your question about how the client should know what the JSON payload they are POSTing and PUTing should look like - this should be reflected in your API documentation. I'm not sure if there is a better tool for this, but Swagger provides a spec that allows you to document what your request bodies should look like using JSON Schema - check out this page for how to define your schemas and this page for how to reference them as a parameter of type body. Unfortunately, Swagger doesn't visualise the request bodies in it's fancy web UI yet, but it's is open source, so you could always add something to do this.
Original Answer
Check out William's comment in the discussion thread on that page - he suggests a way to avoid the exploit altogether which means you can safely use a JSON array at the root of your response and then you need not worry about either of you questions.
The exploit you link to relies on your API using a Cookie to authenticate a user's session - just use a query string parameter instead and you remove the exploit. It's probably worth doing this anyway since using Cookies for authentication on an API isn't very RESTful - some of your clients may not be web browsers and may not want to deal with cookies.
Why Does this fix work?
The exploit is a form of CSRF attack which relies on the attacker being able to add a script tag on his/her own page to a sensitive resource on your API.
<script src="http://mysite.com/api/columns"></script>
The victims web browser will send all Cookies stored under mysite.com to your server and to your servers this will look like a legitimate request - you will check the session_id cookie (or whatever your server-side framework calls the cookie) and see the user is authenticated. The request will look like this:
GET http://mysite.com/api/columns
Cookie: session_id=123456789;
If you change your API you ignore Cookies and use a session_id query string parameter instead, the attacker will have no way of tricking the victims web browser into sending the session_id to your API.
A valid request will now look like this:
GET http://mysite.com/api/columns?session_id=123456789
If using a JavaScript client to make the above request, you could get the session_id from a cookie. An attacker using JavaScript from another domain will not be able to do this, as you cannot get cookies for other domains (see here).
Now we have fixed the issue and are ignoring session_id cookies, the script tag on the attackers website will still send a similar request with a GET line like this:
GET http://mysite.com/api/columns
But your server will respond with a 403 Forbidden since the GET is missing the required session_id query string parameter.
What if I'm not authenticating users for this API?
If you are not authenticating users, then your data cannot be sensitive and anyone can call the URI. CSRF should be a non-issue since with no authentication, even if you prevent CSRF attacks, an attacker could just call your API server side to get your data and use it in anyway he/she wants.
I would go for 'd' because it clearly separates the 'envelope' of your resource from its content. This would also make it easier for consumers to parse your responses, as opposed to 'guessing' the name of the wrapping property of a given resource before being able to access what it holds.
I think you're talking about two different things:
POST request should be sent in application/x-www-form-urlencoded. Your response should basically mirror a GET if you choose to include a representation of the newly created resource in your reply. (not mandatory in HTTP).
PUTs should definitely be symmetric to GETs. The purpose of a PUT request is to replace an existing resource representation with another. It just makes sense to have both requests share the same conventions, doesn't it?
Go with 'Columns' because it is semantically meaningful. It helps to think of how JSON and XML could mirror each other.
If you would PUT the collection back, you might as well use the same media type (syntax, format, what you will call it.)
I'm developing a RESTful interface which is used to provide JSON data for a JavaScript application.
On the server side I use Grails 1.3.7 and use GORM Domain Objects for persistence. I implemented a custom JSON Marshaller to support marshalling the nested domain objects
Here are sample domain objects:
class SampleDomain {
static mapping = { nest2 cascade: 'all' }
String someString
SampleDomainNested nest2
}
and
class SampleDomainNested {
String someField
}
The SampleDomain resource is published under the URL /rs/sample/ so /rs/sample/1 points to the SampleDomain object with ID 1
When I render the resource using my custom json marshaller (GET on /rs/sample/1), I get the following data:
{
"someString" : "somevalue1",
"nest2" : {
"someField" : "someothervalue"
}
}
which is exactly what I want.
Now comes the problem: I try to send the same data to the resource /rs/sample/1 via PUT.
To bind the json data to the Domain Object, the controller handling the request calls def domain = SampleDomain.get(id) and domain.properties = data where data is the unmarshalled object.
The binding for the "someString" field is working just fine, but the nested object is not populated using the nested data so I get an error that the property "nest2" is null, which is not allowed.
I already tried implementing a custom PropertyEditorSupport as well as a StructuredPropertyEditor and register the editor for the class.
Strangely, the editor only gets called when I supply non-nested values. So when I send the following to the server via PUT (which doesn't make any sense ;) )
{
"someString" : "somevalue1",
"nest2" : "test"
}
at least the property editor gets called.
I looked at the code of the GrailsDataBinder. I found out that setting properties of an association seems to work by specifying the path of the association instead of providing a map, so the following works as well:
{
"someString" : "somevalue1",
"nest2.somefield" : "someothervalue"
}
but this doesn't help me since I don't want to implement a custom JavaScript to JSON object serializer.
Is it possible to use Grails data binding using nested maps? Or do I really heave to implement that by hand for each domain class?
Thanks a lot,
Martin
Since this question got upvoted several times I would like to share what I did in the end:
Since I had some more requirements to be implemented like security etc. I implemented a service layer which hides the domain objects from the controllers. I introduced a "dynamic DTO layer" which translates Domain Objects to Groovy Maps which can be serialized easily using the standard serializers and which implements the updates manually. All the semi-automatic/meta-programming/command pattern/... based solutions I tried to implement failed at some point, mostly resulting in strange GORM errors or a lot of configuration code (and a lot of frustration). The update and serialization methods for the DTOs are fairly straightforward and could be implemented very quickly. It does not introduce a lot of duplicate code as well since you have to specify how your domain objects are serialized anyway if you don't want to publish your internal domain object structure. Maybe it's not the most elegant solution but it was the only solution which really worked for me. It also allows me to implement batch updates since the update logic is not connected to the http requests any more.
However I must say that I don't think that grails is the appropriate tech stack best suited for this kind of application, since it makes your application very heavy-weight and inflexbile. My experience is that once you start doing things which are not supported by the framework by default, it starts getting messy. Furthermore, I don't like the fact that the "repository" layer in grails essentially only exists as a part of the domain objects which introduced a lot of problems and resulted in several "proxy services" emulating a repository layer. If you start building an application using a json rest interface, I would suggest to either go for a very light-weight technology like node.js or, if you want to/have to stick to a java based stack, use standard spring framework + spring mvc + spring data with a nice and clean dto layer (this is what I've migrated to and it works like a charm). You don't have to write a lot of boilerplate code and you are completely in control of what's actually happening. Furthermore you get strong typing which increases developer productivity as well as maintainability and which legitimates the additional LOCs. And of course strong typing means strong tooling!
I started writing a blog entry describing the architecture I came up with (with a sample project of course), however I don't have a lot of time right now to finish it. When it's done I'm going to link to it here for reference.
Hope this can serve as inspiration for people experiencing similar problems.
Cheers!
It requires you to provide teh class name:
{ class:"SampleDomain", someString: "abc",
nest2: { class: "SampleDomainNested", someField:"def" }
}
I know, it requires different input that the output it produces.
As I mentioned in the comment earlier, you might be better off using the gson library.
Not sure why you wrote your own json marshaller, with xstream around.
See http://x-stream.github.io/json-tutorial.html
We have been very happy with xstream for our back end (grails based) services and this way you can render marshall in xml or json, or override the default marshalling for a specific object if you like.
Jettison seems to produce a more compact less human readable JSON and you can run into some library collision stuff, but the default internal json stream renderer is decent.
If you are going to publish the service to the public, you will want to take the time to return appropriate HTTP protocol responses for errors etc... ($.02)