Amazon's web API uses a "query API" for non-CRUD operations by using a querystring parameter to specify the operation. I want to implement non-CRUD operations in a similar manner.
Is there any way to map a POST resource method using Jersey JAX-RS dependent on the value of a particular querystring parameter? For example I would like to do something like this:
#POST #Query(name="xaction", value="move")
public Response move(#QueryParam("source") String source, #QueryParam("dest") String dest)
{
...
}
#POST #Query(name="xaction", value="copy")
public Response copy(#QueryParam("source") String source, #QueryParam("dest") String dest)
{
...
}
In the above example I would expect a framework would dispatch to the appropriate method depending on the value of the "xaction" querystring parameter regardless of URI path. Unfortunately I do not have the luxury of using paths or methods to distinguish these operations. I am open to other library suggestions that are compatible with JAX-RS or custom implementations to resolve this.
REST is not Remote Procedure Call (RPC). Even if Amazon is publishing an API like this, it is still not RESTful.
JAX-RS does not provide a mapping you describe for good reasons. Every Resource must be uniquely identifiable by the URI which includes the full path and all query parameters. URI like you describe don't identify Resources but call procedures.
Ask yourself these questions:
What are your Resources?
Do actions on Resources easily map to HTTP verbs?
If not, can actions on Resources me modeled as Resources?
As example for 3., you could thing about a MoveResource and a CopyReource.
A JSON Representation of a MoveResource could look like this:
{
"source": "/path/to/source",
"dest": "/path/to/dest"
}
Creating such a MoveResource and thus triggering a move could be done by a POST to the collection Resource at /moves. This POST would return 201 Created with a Location header like /moves/42. A GET to this Resource could return the state of the MoveResource:
{
"source": "/path/to/source",
"dest": "/path/to/dest",
"status": "success"
}
The same could be done for a CopyResource.
Related
I commence in REST and I have some questions:
What type must the controller return? Typically, I'm asking if my Rest #Controller must return Item object as it is or encapsulate it in ResponseEntity in order to specify http-status-code.
What http status code to use in a GET method on a particular item ("/items/2") if the given item does not exists: HttpMediaStatus.OK(200) and null return or HttpStatus.NO_CONTENT(204) and null return ?
Second part: I saw it was possible to specify #Produces and #Consumes on WS method but what the use of that? My application and my methods work so, why specify MediaType.APPLICATION_JSON_VALUE? Doesn't Spring/SpringBoot automatically convert Item or ResponseEntity into json?
Context: using Spring Boot, hibernate, REST webservice.
Thank you.
Many questions in one, I'll provide short answers with a bunch of link to relevant articles and the reference documentation.
What type must the controller return?
Depends on your annotation and the RESTful-ness of your service. There are three annotations you can use for controllers: #Controller, #RestController and #RepositoryRestController.
Controller is the base annotation to mark your class as a controller. The return type of the controller endpoint methods can be many things, I invite you to read this dedicated post to get a grasp of it.
When developing a pure-REST service, you will focus on using RestController and RepositoryRestController.
RestControlleris Controller + ResponseBody. It binds the return value of the endpoint method to the web response body:
#RestController
public ItemController {
#RequestMapping("/items/{id}")
public Item getItem(#PathVariable("id") String id) {
Item item = ...
return item;
}
}
With this, when you hit http:/.../api/items/foo, Spring does its magic, automatically converting the item to a ResponseEntity with a relevant 40X status code and some default HTTP headers.
At some point, you will need more control over the status code and headers, while still benefiting from Spring Data REST's settings. That's when you will use RepositoryRestController with a ResponseEntity<Item> as return type, see the example the Spring Data REST reference.
What http status code to use in a GET method on a particular item if the given item does not exists?
Bluntly said: use HttpStatus.NOT_FOUND. You're looking for a resource that does not exist, there's something wrong.
That being said, it is completely up to you to decide how to handle missing resources in your project. If your workflow justifies it, a missing resource could be something completely acceptable that indeed returns a 20X response, though you may expect users of your API to get confused if you haven't warned them or provided some documentation (we are creatures of habits and conventions). But I'd still start with a 404 status code.
(...) #Produces and #Consumes on WS method but what the use of that? My application and my methods work so, why specify MediaType.APPLICATION_JSON_VALUE? Doesn't Spring/SpringBoot automatically convert Item or ResponseEntity into json?
#Consumes and #Produces are respectively matched against content-type and accept headers from the request. It's a mean of restricting the input accepted and the output provided by your endpoint method.
Since we're talking about a REST service, communications between clients of the API and the service are expected to be JSON-formatted. Thanks to Spring HATEOAS, the answer are actually formatted with the application/hal+json content-type.
In that scenario, you can indeed not bother with those two annotations. You will need them if you develop a service that accepts different content-types (application/text, application/json, application/xml...) and provides, for instance, HTML views to users of your website and JSON or XML response to automated clients of your service.
For real life examples:
Facebook provides the Graph API for applications to read to/write from its graph, while users happily (?) surf on web pages
Google does the same with the Google Maps API
I'm defining a RESTful API for a TV broadcaster, specifically what the path should look like when asking for a subset of data. For example if I wanted to get the whole content for a particular channel, language on that channel between a specific date, how would I filter by date? The path below seems too long:
endpoint.com/content/channels/{channel_name}/language/french/from/20160701/to/20160801
An alternative I saw is to 'treat the search as a resource' and POST the date range filters to it in the request body, as mentioned here on SO: (How to design RESTful search/filtering?)
Any thoughts?
I will suggest you use #QueryParam annotation to filter your resources by getting it from URI.
To filter the resource you can use an URI like
/channel_name?language=french&from=20160701&to=20160801
Using JAX-RS you then can access the these values:
#GET
#Path("/channel_name")
List<Content> getContent(#QueryParam("language")String lang,
#QueryParam("from")Long from,
#QueryParam("to")Long to) {
// your logic
}
Of course you need to take care of exceptions and the repsonse including status codes in this case.
I also work for a TV Broadcaster and the approach we have taken is to post the search criteria through a resource. Much easier to handle and doesn't create an endless path.
Interface :
#POST
#Path("/lookup")
#Consumes(MediaType.APPLICATION_JSON)
#Produces(MediaType.APPLICATION_JSON)
List<Content> getContent(CriteriaSearch cr);
Implementation :
#Override
#Public
public List<ContentInfo> getContent(CriteriaSearch searchCriteria) {
List<ContentInfo> contentInfos = contentManager.lookupContent(searchCriteria);
...
I am struggling with a design aspect of my restful api for templating collections of resources.
The endpoint calls for a json with the name to a particular template and a collections of tokens. The API will then create entries into numerous tables and use the tokens where appropriate.
A very simple example is:
*{
'template': 'DeviceTemplate'
'tokens': [
'customer': 1234,
'serial_number': '12312RF3242a',
'ip_address': '1.1.1.1'
]
}*
This creates a new device for the customer with that ip address along with several other objects, for instance interfaces, device users etc etc. I use the tokens in various places where needed.
I'm not sure how to make this endpoint restful.
The endpoint for /device is already taken if you want to create this resource individually. The endpoint I need is for creating everything via the template.
I want to reserve the POST /template endpoint for creating the actual template itself and not for implementing it with the tokens to create the various objects.
I want to know how to call the endpoint without using a verbs.
I also want to know if its a good idea to structure a POST with a nested JSON.
I'd suggest that you create an action on the template object itself. So right now if you do /templates/<id> you are given an object. You should include in that object a url endpoint for instantiating an instance of that template. Github follows a scheme that I like a lot [1] where within an object there will be a key pointing to another url with a suffix _url. So for instance, your response could be something like:
{
"template": "DeviceTemplate",
"id": "127",
...
"create_url": "https://yourdomain.com/templates/127/create",
...
}
Then this way you treat a POST to that endpoint the same as if this template (DeviceTemplate) was its own resource.
The way to conceptualize this is you're calling a method on an object instead of calling a function.
[1] - For example https://developer.github.com/v3/#failed-login-limit
Suppose I have a RESTful API for managing orders which uses HAL to facilitate HATEOAS:
GET /orders/2
{
"_links": {
"self": "/orders/2",
"items": "/orders/2/items"
},
"subtotal": 30.0,
"shipped": false
}
I want to write my client (application) using a set of interfaces so that, assuming that implementations of these interfaces are DI-d/built by DI-d factories, etc., I don't really (want to) have to care that they're backed by my RESTful API. As an example (pseudo C#/Java):
public interface Order {
public void addItem(Item item);
public float getSubtotal();
public boolean getShipped();
}
Order order = ...;
Item item = ...;
order.addItem(item);
...(order.getSubtotal())...;
My question is: can I/does it make sense to generate implementations of the Order/Item interface from the API? By this I mean in a manner similar to that offered with C#/web services which export WSDLs.
I've been thinking about implementing OPTIONS for resources such as /orders and /orders/{id} so that I'd effectively have a HATEOAS API for traversing the schema of the API:
GET /orders/* (I'd need a suitable wildcard of course)
{
"_links": {
"addItem": {
"href": "/orders/{id}/items",
"templated": true,
"type": "method"
}
}
}
Of course I could make this part of the _links object returned with any given resource (/orders/2, for instance) but that precludes static code generation.
I'm wondering if there's a sensible way to encapsulate the fact that if a particular link is provided, the related action should be available/performed, otherwise not.
Note: In case it matters, I'm actually working in JavaScript (specifically with AngularJS). However, I'd still like to write my application using a set of conceptual interfaces/contracts.
My question is: can I/does it make sense to generate implementations
of the Order/Item interface from the API? By this I mean in a manner
similar to that offered with C#/web services which export WSDLs.
It partially makes sense. By a simple CRUD API you can map the resources to the entities. By complex applications it does not work, because you map URIs to resources and METHOD URI pairs to operations. So every time if you need an operation not defined by HTTP, you have to create a new resource or at least a new URI for an already existing resource.
Some examples:
transfer money from one account to another: POST /transfer [acc1, acc2, amount, currency] - the transfer does not necessary exist as an entity in your domain logic (don't try that kind of solution in production code unless you want bankruptcy :D)
sending an email to another user: POST /messages [recipient, message]
you can map resources to value objects too: GET /users/123/address
you can use URIs to map reduce a collection: GET /users?name="John"
you can use PUT /users/123 [details] instead of POST /users [details] to create a new user
you can use POST /player/123/xp/increment 10 instead of PUT /player/123/xp [xp+10] to update the experience points of a player
About the WSDL like solutions you can read alot more here: Third Generation Web APIs - Markus Lanthaler.
My personal opinion that it does not worth the effort to build such a system, because it has more drawbacks than advantages.
I am currently using Jersey Framework (JAX-RS implementation) for building RESTful Web Services. The Resource classes in the project have implemented the standard HTTP operations - GET,POST & DELETE. I am trying to figure out how to send request parameters from client to these methods.
For GET it would be in the query string(extract using #QueryParam) and POST would be name/value pair list (extract using #FormParam) sent in with the request body. I tested them using HTTPClient and worked fine. For DELETE operation, I am not finding any conclusive answers on the parameter type/format. Does DELETE operation receive parameters in the query string(extract using #QueryParam) or in the body(extract using #FormParam)?
In most DELETE examples on the web, I observe the use of #PathParam annotation for parameter extraction(this would be from the query string again).
Is this the correct way of passing parameters to the DELETE method? I just want to be careful here so that I am not violating any REST principles.
Yes, its up to you, but as I get REST ideology, DELETE URL should delete something that is returned by a GET URL request. For example, if
GET http://server/app/item/45678
returns item with id 45678,
DELETE http://server/app/item/45678
should delete it.
Thus, I think it is better to use PathParam than QueryParam, when QueryParam can be used to control some aspects of work.
DELETE http://server/app/item/45678?wipeData=true
The DELETE method should use the URL to identify the resource to delete. This means you can use either path parameters or query parameters.
Beyond that, there is no right and wrong way to construct an URL as far as REST is concerned.
You can use like this
URL is http://yourapp/person/personid
#DELETE
#Path("/person/{id}")
#Produces(MediaType.APPLICATION_JSON)
public Response deletePerson(#PathParam("id") String id){
Result result = new Result();
try{
persenService.deletePerson(id);
result.setResponce("success");
}
catch (Exception e){
result.setResponce("fail");
e.printStackTrace();
}
return Response.status(200).entity(result).build();
}
#QueryParam would be the correct way. #PathParam is only for things before any url parameters (stuff after the '?'). And #FormParam is only for submitted web forms that have the form content type.