I have a design question on REST. I need to expose a validate method as a rest resource. Let us say it looks like this
public ValidatedResult validate(ObjectToBeValidated object)
ObjectToBeValidated is a class that contains the actual Object and also some parameters concerning the validation.
When I design this as a Restful resource, which action do I use? From my understanding GET is the action that best suits this case. If that is so, how I can pass my ObjectTobeValidated as an object but not as URL parameters? I shy away from URL parameters because ObjectToBeValidated may contain a lot of properties, ending up with an URL like below which is feel is too long
http://localhost/rest/validate?prop1=somevalu&prop2=somevalue&prop3=something&prop11=somevalu&prop22=somevalue&prop33=something
Any help would be appreciated
Thanks
Kay
The HTTP standard allows you to use the POST method. It does not necessary need to have a side effect.
The action performed by the POST method might not result in a resource
that can be identified by a URI. In this case, either 200 (OK) or 204
(No Content) is the appropriate response status, depending on whether
or not the response includes an entity that describes the result.
HTTP 1.1 / method definitions / POST
In your case you can do something like this if you want to follow the noun-verb approach Tim suggested:
POST /api/my/object/validator
Be aware that by REST the messages must be self-descriptive, so either you need a vendor MIME type or you need to add meta-data e.g. RDF to describe what this link does and what params are allowed. Otherwise we are not talking about REST, just a regular webapp.
Related
Assume you have a REST service that already gets users by id, so the url looks something like
GET /users/{userId}
But you want to create a duplicate web service that gets users by email, so:
GET /users/{email}
Which is better?
Method 1:
Same method:
/users/{input}
...
if(isEmail(input)) queryByEmail(input);
else queryById(input);
Method 2:
Different Method:
GET /users/{userId}
GET /usersByEmail/{email}
Since there is no actual overlap between email addresses and IDs. I would just use same endpoint for both. Especially if GET /users/{id} is already a published interface.
So, I would go with 1st method.
GET /users/{identifier}
Then on the API server you have to add a small check, whether {identifier} is a number or not.
I would also like to note, that "pretty URLs" do not make it REST :) You probably will want to watch this lecture: https://www.youtube.com/watch?v=pspy1H6A3FM
My personal preference would be,
GET /users/id/{id}
GET /users/email/{email}
But it all depends on what you the rest endpoints to look like.
Which is better?
REST doesn't care; from the perspective of the client, the URI is opaque. The clients concerns are following links/submitting forms/completing templates.
Information encoded into the URI is done at the server's discretion and for its own exclusive use.
So you can use any spelling you like. As a rule, it's a good idea to conform to local spelling conventions (in much the same way that your variable names in code should conform to your coding conventions). But your clients shouldn't need to know the details of those conventions.
/users/{input}
...
if(isEmail(input)) queryByEmail(input);
else queryById(input);
Note that you aren't necessarily deeply committed to one approach; that's part of the point of decoupling the identifiers from the representations. For instance, your implementation could just as easily look like
/users/{input}
...
if(isEmail(input)) redirectTo(/users/email/{input});
else redirectTo(/users/id/{input});
which allows clients that have bookmarked the original URI to arrive at the correct resource.
I have a REST API with a PUT endpoint which looks like this:
api.website.net/resources/resourceId
The controller implementation of this endpoint looks like follows:
#RequestMapping("/resources/{resourceId}")
public Resource putResource(#PathVariable(value = "resourceId") String resourceId, #RequestBody(required = false) Resource resource)
There is the case where a user may perform a PUT on this resource, but neglect to provide an object in the body (i.e. resource == null is true).
Which of the following approaches is more RESTful?
Have a PUT on this endpoint simply return the existing Resource object with no changes, or
Make the object required in the request body?
Note that the object exists at the given URL in both cases.
From my interpretation of the definition of PUT, it would be more RESTful to require a body because the definition seems to imply an entity exists:
From https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
9.6 PUT
The PUT method requests that the enclosed entity be stored under the
supplied Request-URI.
The part which says "the enclosed entity" to me implies an entity actually exists.
I think if you PUT nothing, it would end up being the same as a DELETE. This just makes me think even more that a body should be required for PUT and DELETE should be used for that functionality.
All this being said, it is certainly possible to implement something which accepts PUT requests with no body, though as I said I don't think this would be RESTful.
There is some discussion about this topic here: Is an HTTP PUT request required to include a body?
There is the case where a user may perform a PUT on this resource, but neglect to provide an object in the body (i.e. resource == null is true).
Intriguing.
The PUT method is mentioned in appendix D of the HTTP/1.0 spec, was included in the HTTP/1.1 specification, and is currently defined within the content and semantics chapter of the 2014 HTTP/1.1 spec.
Its use case lineage is page publishing, taking the representation embedded within the request and writing it into the servers own store.
A PUT request, with no payload, is analogous to a request that you upsert an empty file into a specific location. That's a perfectly reasonable thing for a file system or a key value store to do.
Which of the following approaches is more RESTful?
The applicable constraint of REST is the uniform interface - PUT on this resource should have the same semantics as PUT everywhere else on the web. So it's important that PUT handling is idempotent, and that a successful PUT creates/replaces the state of the resource with the state defined by the representation in the request.
Have a PUT on this endpoint simply return the existing Resource object with no changes
Make the object required in the request body?
The second of these, I think, is closer to what you want. You can't force the client to send you a valid representation of your resource, but you can reject any request that doesn't provide a valid representation. So if you find that the provided representation isn't satisfactory, you should be thinking in terms of 400 Bad Request or 409 Conflict.
Note: when sending a 4xx response, you are normally sending a representation of the problem, rather than a representation of the resource.
Except when responding to a HEAD request, the server SHOULD send a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition.
Returning a copy of the current state of the resource isn't useful for telling the client what went wrong.
Let's assume we have two methods on the REST controller:
#ResponseStatus(HttpStatus.OK)
#RequestMapping(value = "/{userId}", method = RequestMethod.GET)
#ResponseBody
public UserDTO showUserDetails(#PathVariable("userId") Long userId) {
/* code here */
}
#ResponseStatus(HttpStatus.ACCEPTED)
#RequestMapping(value = "/{userId}", method = RequestMethod.POST)
#ResponseBody
public UserDTO editUser(#PathVariable("userId") Long userId, UserDTO userToEdit) {
/* code here */
}
So we have two identical URIs mappings, but supporting different HTTP requests. My question is: is this approach acceptable in terms of designing APIs? Or it is better to map second method to something like /{userId}/edit ?
Also, when using hateoas paradigm, the response will look somewhat strange:
"links":[{"rel":"self","href":"http://1localhost:8080/root/users/1"},{"rel":"edit","href":"http://localhost7:8080/root/users/1"}]
With 2 different URIs looking identical.
In terms of REST API design, you mapping is correct. For a given resource, you should interact with it via a single URI, In you example:
http://localhost:8080/root/users/1
And specify the operation via HTTP verbs.
Check the RESTful API HTTP methods in REST - Applied to web services, for an example.
I would definitely change the request mappings. For your editUser I'd add a /edit/ so your URL would look like http://localhost7:8080/root/users/edit/1
For the show you could add a /view/ to the URL, but that's not really necessary, but for the edit I'd personally prefer to have the URL be selfexplanatory
From a REST perspective what matters that you use the proper HTTP method and a single resource identifier (URL) is mapped only to a single resource. The URL structure does not matter. It matters only for you by routing the requests.
Your choice of method is bad. By edit you have to use PUT (full) or PATCH (partial) instead of POST. If you cannot use these methods because of some purposes (for example you use plain HTML forms to send requests), then you should use method override. For example send the real method in a _method param, in the body, in the query, or in a header. (It does not really matter which you choose because it is already an ugly workaround. Most ppl prefer the query.)
By choosing the URL most ppl prefer to use only nouns. This is because you don't map URLs to operations (like SOAP RPC), which are verbs (and probably nouns). For example POST /GetCurrentPrice. You map URLs to web resources, which are nouns for example GET /currentPrice.
REST is pretty simple. It uses existing standards to describe an uniform interface. Sadly most web developers do not know the HTTP standard. You should read at least the HTTP method definitions, the HTTP status code definitions and the URI RFC. These are the basics by REST.
Im developeing a RESTful Service in which Processes can be executed and proivde a resulting calculation. For this i have modeled the process itself as a Resource (Example: /processes/translate). I want to execute the process by sending a GET request with appended Input Parameter as Query Parameter (Example: /processes/translate?input1=xxxx&input2=xxxxx).
Each process has different Input Parameter which are defined during the process creation in the backend. My Question is how should i document or describe which inputs are needed to execute a process in machine readable form. For Example in XML.
Until now ive integrated atom:link elements in the Representation. i thought that maybe including XFORM could be a soluttion?
Best Regards
Andre
I would not model this with a GET. While it's the easier solution, it's also (IMO) the least RESTful. I would have clients POST a document describing what they want you to translate and your service sends them back a URI where their answer can be found (some translations might take a while).
Example (ommiting a lot of HTTP headers/context)
POST /processes/translate
Content-Type: application/xml
...
<translation-request>
<input1 type="type1">....</input1>
<input2 type="type5">....</input2>
</translation-request>
Response:
200 OK
Content-Location: /processes/translate/jobs/1234
....
That's always an interesting question. We have a project called RESTx (http://restx.org), with which you can create RESTful web services very easily. You can write custom component code in either Java or Python and then create RESTful resources by sending parameter sets to the server, which are then stored. Each parameter set gets its own URI, though, so you can always just run the code with those parameters by accessing the new parameter set's URI.
Importantly, the entire RESTful API, is automatically created. RESTx examines the component code and then assembles the API description. We decided to describe parameters in a way that is human as well as machine readable. You can see examples of what that looks like in a browser or in plain JSON.
I'm the lead developer on that, so please feel free to contact me about any questions you might have.
What is the best way to version REST URIs? Currently we have a version # in the URI itself, ie.
http://example.com/users/v4/1234/
for version 4 of this representation.
Does the version belong in the queryString? ie.
http://example.com/users/1234?version=4
Or is versioning best accomplished another way?
Do not version URLs, because ...
you break permalinks
The url changes will spread like a disease through your interface. What do you do with representations that have not changed but point to the representation that has? If you change the url, you break old clients. If you leave the url, your new clients may not work.
Versioning media types is a much more flexible solution.
Assuming that your resource is returning some variant of application/vnd.yourcompany.user+xml all you need to do is create support for a new application/vnd.yourcompany.userV2+xml media type and through the magic of content negotiation your v1 and v2 clients can co-exist peacefully.
In a RESTful interface, the closest thing you have to a contract is the definition of the media-types that are exchanged between the client and the server.
The URLs that the client uses to interact with the server should be provided by the server embedded in previously retrieved representations. The only URL that needs to be known by the client is the root URL of the interface. Adding version numbers to urls only has value if you construct urls on the client, which you are not suppose to do with a RESTful interface.
If you need to make a change to your media-types that will break your existing clients then create a new one and leave your urls alone!
And for those readers currently saying that this makes no sense if I am using application/xml and application/json as media-types. How are we supposed to version those? You're not. Those media-types are pretty much useless to a RESTful interface unless you parse them using code-download, at which point versioning is a moot point.
I would say making it part of the URI itself (option 1) is best because v4 identifies a different resource than v3. Query parameters like in your second option can be best used to pass-in additional (query) info related to the request, rather than the resource.
Ah, I'm putting my old grumpy hat on again.
From a ReST perspective, it doesn't matter at all. Not a sausage.
The client receives a URI it wants to follow, and treats it as an opaque string. Put whatever you want in it, the client has no knowledge of such a thing as a version identifier on it.
What the client knows is that it can process the media type, and I'll advise to follow Darrel's advice. Also I personally feel that needing to change the format used in a restful architecture 4 times should bring huge massive warning signs that you're doing something seriously wrong, and completely bypassing the need to design your media type for change resiliance.
But either way, the client can only process a document with a format it can understand, and follow links in it. It should know about the link relationships (the transitions). So what's in the URI is completely irrelevant.
I personally would vote for http://localhost/3f3405d5-5984-4683-bf26-aca186d21c04
A perfectly valid identifier that will prevent any further client developer or person touching the system to question if one should put v4 at the beginning or at the end of a URI (and I suggest that, from the server perspective, you shouldn't have 4 versions, but 4 media types).
You should NOT put the version in the URL, you should put the version in the Accept Header of the request - see my post on this thread:
Best practices for API versioning?
If you start sticking versions in the URL you end up with silly URLs like this:
http://company.com/api/v3.0/customer/123/v2.0/orders/4321/
And there are a bunch of other problems that creep in as well - see my blog:
http://thereisnorightway.blogspot.com/2011/02/versioning-and-types-in-resthttp-api.html
These (less-specific) SO questions about REST API versioning may be helpful:
Versioning RESTful services?
Best practices for web service REST API versioning
There are 4 different approaches to versioning the API:
Adding version to the URI path:
http://example.com/api/v1/foo
http://example.com/api/v2/foo
When you have breaking change, you must increment the version like: v1, v2, v3...
You can implement a controller in you code like this:
#RestController
public class FooVersioningController {
#GetMapping("v1/foo")
public FooV1 fooV1() {
return new FooV1("firstname lastname");
}
#GetMapping("v2/foo")
public FooV2 fooV2() {
return new FooV2(new Name("firstname", "lastname"));
}
Request parameter versioning:
http://example.com/api/v2/foo/param?version=1
http://example.com/api/v2/foo/param?version=2
The version parameter can be optional or required depending on how you want the API to be used.
The implementation can be similar to this:
#GetMapping(value = "/foo/param", params = "version=1")
public FooV1 paramV1() {
return new FooV1("firstname lastname");
}
#GetMapping(value = "/foo/param", params = "version=2")
public FooV2 paramV2() {
return new FooV2(new Name("firstname", "lastname"));
}
Passing a custom header:
http://localhost:8080/foo/produces
With header:
headers[Accept=application/vnd.company.app-v1+json]
or:
headers[Accept=application/vnd.company.app-v2+json]
Largest advantage of this scheme is mostly semantics: You aren’t cluttering the URI with anything to do with the versioning.
Possible implementation:
#GetMapping(value = "/foo/produces", produces = "application/vnd.company.app-v1+json")
public FooV1 producesV1() {
return new FooV1("firstname lastname");
}
#GetMapping(value = "/foo/produces", produces = "application/vnd.company.app-v2+json")
public FooV2 producesV2() {
return new FooV2(new Name("firstname", "lastname"));
}
Changing Hostnames or using API Gateways:
Essentially, you’re moving the API from one hostname to another. You might even just call this building a new API to the same resources.
Also,you can do this using API Gateways.
I wanted to create versioned APIs and I found this article very useful:
http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http
There is a small section on "I want my API to be versioned". I found it simple and easy to understand. The crux is to use Accept field in the header to pass version information.
If the REST services require authentication before use, you could easily associate the API key/token with an API version and do the routing internally. To use a new version of the API, a new API key could be required, linked to that version.
Unfortunately, this solution only works for auth-based APIs. However, it does keep versions out of the URIs.
If you use URIs for versioning, then the version number should be in the URI of the API root, so every resource identifier can include it.
Technically a REST API does not break by URL changes (the result of the uniform interface constraint). It breaks only when the related semantics (for example an API specific RDF vocab) changes in a non backward compatible way (rare). Currently a lot of ppl do not use links for navigation (HATEOAS constraint) and vocabs to annotate their REST responses (self-descriptive message constraint) that's why their clients break.
Custom MIME types and MIME type versioning does not help, because putting the related metadata and the structure of the representation into a short string does not work. Ofc. the metadata and the structure will frequently change, and so the version number too...
So to answer your question the best way to annotate your requests and responses with vocabs (Hydra, linked data) and forget versioning or use it only by non backward compatible vocab changes (for example if you want to replace a vocab with another one).
I'd include the version as an optional value at the end of the URI. This could be a suffix like /V4 or a query parameter like you've described. You might even redirect the /V4 to the query parameter so you support both variations.
I vote up for doing this in mime type but not in URL.
But the reason is not the same as other guys.
I think the URL should be unique (excepting those redirects) for locating the unique resource.
So, if you accept /v2.0 in URLs, why it is not /ver2.0 or /v2/ or /v2.0.0? Or even -alpha and -beta? (then it totally becomes the concept of semver)
So, the version in mime type is more acceptable than the URL.