As an example imagine a dynamic pricing system which you can ask for offers moving boxes from 1 place to another. Since the price does not exist before you ask for it it's not as simple as retrieving data from some data-base, but an actual search process needs to run.
What I often see in such scenario's is a request/response based endpoint:
POST /api/offers
{
"customerId" : "123",
"origin" : {"city" : "Amsterdam"},
"destination" : {"city" : "New York"},
"boxes": [{"weight" : 100},{"weight": "200"}]
}
201:
{
"id" : "offerId_123"
"product" : {
"id" : "product_abc",
"name": "box-moving"
}
"totalPrice" : 123.43
}
The request has nothing to do with the response except that one is required to find all information for the other.
The way I interpret "manipulation of resources through representations" I think that this also goes for creation. Following that I would say that one should create the process of searching in stead:
POST /api/offer-searches
{
"request" : {
"customerId" : "123",
"origin" : {"city" : "Amsterdam"},
"destination" : {"city" : "New York"},
"boxes": [{"weight" : 100},{"weight": "200"}]
}
}
201:
{
"id" : "offerSearch_123"
"request" : {
"customerId" : "123",
"origin" : {"city" : "Amsterdam"},
"destination" : {"city" : "New York"},
"boxes": [{"weight" : 100},{"weight": "200"}]
}
offers: [
"id" : "offerId_123"
"product" : {
"id" : "product_abc",
"name": "box-moving"
}
"totalPrice" : 123.43
]
}
Here the request and the response are the same object, during the process it's enhanced with results, but both are still a representation of the same thing, the search process.
This has the advantage of being able to "track" the process, by identifying it it can be read again later. You could still have /api/offers/offerId_123 return the created offer to not have to go through the clutter of the search resource. But it also has quite the trade-off: complexity.
Now my question is, is this first, more RPC like approach something we can even call REST? Or to comply to REST constraints should the 2nd approach be used?
Now my question is, is this first, more RPC like approach something we can even call REST? Or to comply to REST constraints should the 2nd approach be used?
How does the approach compare to how we do things on the web?
For the most part, sending information to a server is realized using HTML forms. So we are dealing with a lot of requests that look something like
POST /efc913bf-ac21-4bf4-8080-467ca8e3e656
Content-Type: application/x-www-form-urlencoded
a=b&c=d
and the responses then look like
201 Created
Location: /a2596478-624f-4775-a490-09edb551a929
Content-Location: /a2596478-624f-4775-a490-09edb551a929
Content-Type: text/html
<html>....</html>
In other words, it's perfectly normal that (a) the representations of the resource are not the information that was sent to the server, but intead something the server computed from the information it was sent and (b) not necessarily of the same schema as the payload of the request... not necessarily even the same media type.
In an anemic document store, you are more likely to be using PUT or PATCH. PATCH requests normally have a patch document in the request-body, so you would expect the representations to be different (think application/json-patch+json). But even in the case of PUT, the server is permitted to make changes to the representation when creating its resource (to make it consistent with its own constraints).
And of course, when you are dealing with responses that contain a representation of "the action", or representations of errors, then once again the response may be quite dissimilar from the request.
TL;DR REST doesn't care if the representation of a bid "matches" the representation of the RFP.
You might decided its a good idea anyway - but it isn't necessary to satisfy REST's constraints, or the semantics of HTTP.
Related
I am currently building an app using Firebase, and decided to implement a chat as well.
I was able to use JSQMessagesVC as a GUI, and get the Firebase chat aspect working as well (by combining 2 UID's to create a chatroom, ex: /123_456). However, I am lost on how to notify the other user if they have received a message. (If user 123 opens chatroom 123_456 and sends a message in it, how do I notify user 456 that they have received a message?)
Thanks for the help!
Your question is more related to designing your database. In case implementing chat functionalities you need to rethink about your database structure again. Its all about database structure as Firebase doesn't provide you any trigger so that you can do some actions on other nodes (i.e. database tables) with your primary action in the node you're in.
Though you might've read all those tutorials already, you can take a look again anyway about structuring your data
Here's a nice chat example which might help you in your case. Though its referring to a group chat. You might take a look at how the database is structured for this purpose.
Basically, you need to put some extra actions from client side in different nodes when someone opens a room to chat with others.
Oh here's another SO Answer you should take a look at.
I had the same issue, which I solved by putting in an additional node where each user has a number of chatrooms. put an observer on the user in the chatroom (in below case "0888a5dc-fe8d-4498-aa69-f9dd1361fe54"), with a counter, a description and a timestamp. each new message, update counter, and lastMessage, etc. see below:
"Messages" : {
"0888a5dc-fe8d-4498-aa69-f9dd1361fe54" : {
"0888a5dc-fe8d-4498-aa69-f9dd1361fe5451879163-8b35-452b-9872-a8cb4c84a6ce" : {
"counter" : 2,
"description" : "Breta",
"lastMessage" : “cool”,
"lastUser" : "51879163-8b35-452b-9872-a8cb4c84a6ce",
"messageType" : "txt",
"sortTimestamp" : -1.459518501758476E9,
"updatedAction" : 1.459518501758468E9,
"userId" : "51879163-8b35-452b-9872-a8cb4c84a6ce"
},
"0888a5dc-fe8d-4498-aa69-f9dd1361fe547bfe8604-58ad-4d18-a528-601b76dd2206" : {
"counter" : 0,
"description" : "Romeo",
"lastMessage" : “yep”,
"lastUser" : "0888a5dc-fe8d-4498-aa69-f9dd1361fe54",
"messageType" : "txt",
"sortTimestamp" : -1.459527387138615E9,
"updatedAction" : 1.459527387138613E9,
"userId" : "7bfe8604-58ad-4d18-a528-601b76dd2206"
}
}
Our stack currently uses mongoose as a ODBM and I was wondering how exactly I should implement a RESTFUL request to determine whether a foregin key gets populated(i.e the forgeign key _id property gets replaced with the either the entire document or part of the document from another collection).
I know I could send up something like
?populate=CollectionName&populateFields=fieldsnames`
via a query string but something about that seems hacky to me and I was wondering what's considered the standard/best practice in this situation
MongoDb doesn't have joins. If the associated data is small enough, then it's suggested to embed the document.
If you take that appoarch, then you could perform this simple query to check if the embedded document field is a document.
0 < db.products.count({_id : 3, rebateProgram : { $type : 3} })
In mongoose, I think it's
0 < productModel.find({}).where({_id : 3, rebateProgram : { $type : 3} }).count()
rebateProgram : {$type : 3} means only match the rebateProgram field if it's an with an embedded document.
3 is the BSON type for embedded document.
RESTful URL
A restful url to check the a property on a document could look like this.
The request would be a GET because you're retrieving a value and not modifying anything data.
GET: /??/:collectionName/:documentId/action
Example:
Request:
GET: /api/products/3/status?hasObject=rebateProgram
Response:
{
id: 3,
hasObject : { rebateProgram : true },
success : true,
errMsg : ""
}
However if it's always going to be the same field you're checking for, then include the status of the embedded field in the response.
Like this.
Example:
Request:
GET: /api/products/3/status
Response:
{
id: 3,
hasValidRebateProgram : true,
success : true,
errMsg : ""
}
More info:
Doc: BSON spec
Allowing query parameters that lets the client add or remove fields returned by a resource's endpoint is not hacky in my opinion. I recommend reading this article on RESTful best practices. So your URL would look something like this:
Assuming you're talking about a GET route
GET /users/:user_id?fields=field1,some_other_field
You shouldn't need to represent your database in a RESTful URL. Think from a client's perspective. What would make sense to you if you didn't design the database? I think an API should expose behavior, not a database.
I'm developing a service that has a RESTful API. The API is JSON-based and uses HAL for HATEOAS links between resources.
The implementation shouldn't matter to the question, but I'm using Java and Spring MVC.
Some example requests:
GET /api/projects
{
"_links" : {
"self" : {
"href" : "example.org/api/projects"
},
"projects" : [ {
"href" : "example.org/api/projects/1234",
"title" : "The Project Name"
}, {
"href" : "example.org/api/projects/1235",
"title" : "The Second Project"
} ]
},
"totalProjects" : 2,
}
GET /api/projects/1234
{
"_links" : {
"self" : {
"href" : "example.org/api/projects/1234"
},
"tasks" : [ {
"href" : "example.org/api/projects/1234/tasks/543",
"title" : "First Task"
}, {
"href" : "example.org/api/projects/1234/tasks/544",
"title" : "Second Task"
} ]
},
"id" : 1234,
"name" : "The Project Name",
"progress" : 60,
"status" : "ontime",
"targetDate" : "2014-06-01",
}
Now, how should I test GET requests to a single project? I have two options and I'm not sure which one is better:
Testing for /api/projects/{projectId} in the tests, replacing {projectId} with the id of the project the mock service layer expects/returns.
Requesting /api/projects/ first then testing the links returned in the response. So the test will not have /api/projects/{projectId} hardcoded.
The first option makes the tests much simpler, but it basically hardcodes the URLs, which is the thing HATEOAS was designed to avoid in the first place. The tests will also need to change if I ever change the URL structure for one reason or another.
The second option is more "correct" in the HATEOAS sense, but the tests will be much more convoluted; I need to traverse all parent resources to test a child resource. For example, to test GET requests to a task, I need to request /api/projects/, get the link to /api/projects/1234, request that and get the link to /api/projects/2345/tasks/543, and finally test that! I'll also need to mock a lot more in each test if I test this way.
The advantage of the second option is that I can freely change the URLs without changing the tests.
If your goal is testing a Hypermedia API, then your testing tools need to understand how to process and act on the hypermedia contained in a resource.
And yes, the challenge is how deep you decide to traverse the link hierarchy. Also, you need to account for non-GET methods.
If these are automated tests a strategy would be to organize the tests in resource units. Only test the links returned in the resource under test: a module for projects, and others for project, tasks, task, and so on. This does require some hard-coding of well-known URLs for each module, but allows you to manage the tests more easily around your resource model.
I don't know about HATEOAS . But what I can say.
You may try a swat - a perl,curl based DSL for web, rest services test automation. Swat was designed to simplify URL "juggling" you probably talking about here. A quick reference for how this could be done by SWAT ( a strait forward way, but there are more elegant solutions ):
$ mkdir -p api/project/project_id
$ echo '200 OK' > api/project/project_id/get.txt
$ nano api/project/project_id/hook.pm
modify_resource(sub{
my $r = shift; # this is original rout api/project/project_id/
my $pid = $ENV{project_id};
$r=~s{/project_id}{$pid} # dynamically setup route to api/project/{project_id}
return $r;
});
$ project_id=12345 swat http://your-rest-api # run swat test suite!
A more complicated examples could be found at the documentation.
(*) Disclosure - I am the tool author.
If you use Spring HATEOAS you can use ControllerLinkBuilder (http://docs.spring.io/autorepo/docs/spring-hateoas/0.19.0.RELEASE/api/org/springframework/hateoas/mvc/ControllerLinkBuilder.html) for link creation in your tests as described in http://docs.spring.io/spring-hateoas/docs/0.19.0.RELEASE/reference/html/#fundamentals.obtaining-links. With ControllerLinkBuilder, there is no hard-coded URL-s.
ControllerLinkBuilderUnitTest.java (https://github.com/spring-projects/spring-hateoas/blob/4e1e5ed934953aabcf5490d96d7ac43c88bc1d60/src/test/java/org/springframework/hateoas/mvc/ControllerLinkBuilderUnitTest.java) shows how to use ControllerLinkBuilder in tests.
While researching RESTful APIs for asynchronous operations I ran across the following design pattern:
POST uri:longOperation returns:
HTTP 202
Location: uri:pendingOperation
GET uri:pendingOperation returns:
If operation is running
Return a progress report.
If operation is complete
HTTP 303
Location: uri:operationResponse
GET uri:operationResponse
The response of the asynchronous operation
I find the last step questionable. Consider what happens if the asynchronous operation completes with an error code that doesn't make sense for HTTP GET, such as HTTP 409 ("Conflict").
Isn't HTTP 303 required to point to the response associated with uri:pendingOperation as opposed to uri:operationResponse?
Is using HTTP 303 in this way considered harmful? If not, why?
Is this the best we can do, or is there a better way?
Isn't HTTP 303 required to point to the response associated with uri:pendingOperation as opposed to uri:operationResponse?
The spec doesn't explicitly say it is required, but I tend to agree with you.
Is using HTTP 303 in this way considered harmful? If not, why?
I think you lose capabilities by doing a 303. While it is "nice" to auto-redirect when done, it makes it so that you don't have an opportunity to provide meta data around the results, that can be leveraged for reporting etc... Also many clients don't auto follow 303, so the client may need to do work to follow the 303 Location header anyways.
Is this the best we can do, or is there a better way?
I tend to recommend having the GET uri:pendingOperation return 200 with a status resource always with a reference to the output when it is "complete". Something like
When Incomplete
{
"status" : "PENDING"
}
When Error
{
"status" : "COMPLETE"
"errors" : [
{
"typeId" : "OPERATION_TIMEOUT",
"description" : " "The request was unable to complete because the systems are unresponsive".
}
]
}
When Successful
{
"status" : "COMPLETE"
"links" : {
"result" : {
"href" : "http://api.example.com/finished-resource/1234",
}
]
}
Imagine an API that returns JSON data for a TV listings app like zap2it TV listings.
It's basically a list of TV channels and for each channel the shows that are on currently and beyond. Currently, I have an API that returns all the channels GET /channels. However, there is a need to add the show currently on for each channel in that data. I am thinking of adding a new API, GET /channels/on_now, to differentiate it from the current API. I want to be clear about this for the new API, I don't want to make individual call for each channel, the show-on-now data needs to be returned for all channels. Is this a good REST API design?
Current GET /channels JSON data
[
"channel": {
"channelName": "KRON4",
},
"channel": {
"channelName": "KTOV5",
},
...
]
Expected JSON data for new API GET /channels/on_now below
[
{
"channel": {
"channelName": "KRON4",
},
"on_now": {
"startTime": "2012-06-04T11:30:00",
"endTime": "2012-06-04T12:00:00",
"shortDescription": "Latest local, statewide & national news events, along with sports & weather.",
"shortTitle": "4:30am Newscast"
}
},
{
"channel": {
"channelName": "KTOV5",
},
"on_now": {
"startTime": "2012-06-04T11:30:00",
"endTime": "2012-06-04T12:30:00",
"shortDescription": "Local morning news and weather report",
"shortTitle": "Morning Newscast"
}
},
...next channel...
]
I would advice to concentrate on content, not on URLs.
Example: you've got an entry point, '/'. This is the only URL in the API. GET on it return st like
{
"channels" : {
"href" : "path.to/channels"
},
"programs" : {
"href" : "path.to/programs"
}
}
To retrieve the list of channels, you GET on the corresponding URL - which you then don't need to know before - and obtain, for example:
[
{
"name" : "BBC",
"id" : 452,
"href" : "path.to/channels/452"
},
{
"name" : "FOO",
"id" : 112,
"href" : "path.to/channels/112"
}
]
For detailled information about BBC, you GET on the provided URL:
{
"name" : "BBC",
"id" : 452,
"self" : "path.to/channels/452",
"live_url" : "link.to.bbc.cast",
"whatever" : "bar",
"current" : "path.to/channels/452/current",
"program" : "path.to/channels/452/program"
}
And so on. URLs are discovered on the fly; you are free to modify them anytime. What makes your API is the content: you have to agree with clients about what is returned (fields, types, ...).
You finally call the "current" URL above to obtain information about current program.
Read here for more: http://kellabyte.com/2011/09/04/clarifying-rest/
Edit after OP-comment:
You could introduce an 'embed' parameter so as to limit amount of requests:
GET path.to/channels/452?embed=current
would return:
{
"name" : "BBC",
"id" : 452,
"self" : "path.to/channels/452",
"live_url" : "link.to.bbc.cast",
"whatever" : "bar",
"current" : {
"self" : "path.to/channels/452/current",
"name" : "Morning Show",
"start_time" : "(datetime here)",
"end_time" : "(datetime here)",
"next" : "whatever.comes.ne/xt"
},
"program" : "path.to/channels/452/program"
}
You asked:
Is this a good REST API design?
YES, it is.
Contrary to the other people who have answered, you are free to define any resource you want to, as long as it represents a noun. That includes time-dependent services such as "what's on TV now" or the perrenial example, "current weather in <city>". These service resources are just as valid as more static ones representing a show or channel.
I would however change the URI. /channels looks like a collection resource URI. I would expect it's children to be channels, such as /channels/kron4 (you can use any unique string, not jsut the ID, to identify instance resources).
As such, /channels/on_now looks odd. It looks like a channel called "on_now". Although there's nothing preventing you from using that, it may later conflict with a channel that is called "On Now"! I would simply use /on_now as your URI. /channels/kron4/on_now would obviously be good for a single channel's response too.
/Channels -----------------------> Get All Channels
/Channels/bbc ------------------> Get BBC Channel
/Channels/bbc/Shows -------------> Get All shows in BBC
/Channels/bbc/Shows/Baseball ----> Get the show called "Baseball", in bbc channel
/Channels/bbc/Shows/current -----> Get the Current show running, in bbc channel
Assuming you do not (and will not ) have a show called Current for any of your channels ! :) .
Just appending to the above answer:
/Channels/bbc/Shows/time/now -----> Get all the show played on BBC now
/Channels/bbc/Shows/time/2011-03-27T03:00:00.000+02:00 -----> Get all the show played on BBC on 2011-03-27T03:00:00.000+02:00 .
This is more extensible and you wont have to worry about any show with the name current.
EDIT:
You can get a good headstart of doing such thing if you can get an api-doc access over here https://developer.sdp.nds.com/page/about
As per me, there would be more data needed and api would be something like:
//epg?time=&start=0&limit=1&duration=
This would define a generic api to get the location based tv_listing information based on time and duration. Result would be paginated with all the show between the channel listing occuring in the given time span.
I'm no API expert, but I think you should be thinking in what you are returning instead of where 'looks like makes sense' to place the resource.
One solution will be to treat on_now as a resource.
so your api will be:
/channels (all channels)
/channels/{channel-id} (the {channel-id} channel - could be bbc and can have a collection of shows)
/channels/{channel-id}/shows (shows of channel-id)
/channels/{channel-id}/shows?filter=on_now (you are filtering a result, so i guess it's better to use query string, as if you were doing a query)
then you want to returns what's on now, that's no a property of the channel but a resource of itself. so how to implement that ?
/on_now/ (return a collection of on_now objects, which may be anything, channels, shows, whatever)
/on_now/?channel={channel-id} (this is a filter of the list by channel-id, you are just narrowing the list)
so isn't /channels/{channel-id}/shows?filter=on_now
the same as /on_now/?channel={channel-id} ?
actually, NO.
In the first uri you are getting shows filtered by a on_now.
In the second you are getting on_nows (which can be any representation, not exclusively a show) filtered by channel.
Why I think on_now should be treated as a resource and why is it important ?
While you make this resource separate, you can now have different representations of your resources. Also you have greater flexibility and no collision. Let's say tomorrow you want to show also in the on_now another 'show' that isn't on any channel, this can easily be done, on the other approachs it just has to be on a channel.
You can also later filter the on_now by different criteria, because they are independent objects.
You can also do:
/on_now/{on_now_id}
that will give details of the current show, like when it started, when it will end and also a place a location to /shows/{show-id} so you can reach it later after it's not on now anymore.
Yet, I think best solution would be to have shows as an unconnected resource to channel.
But the most important thing is, i think you should also need to ask yourself if you want shows to be underlying of channels...
And what hints to think of that is the
I don't want to make individual call for each channel, the
show-on-now data needs to be returned for all channels
part.
That leads me to think that shows should NOT be inside the /channels/ path.
That's because another approach will be to have /shows/?filter=on_now if you are only returning shows.
you can have:
/shows/?filters=on_now&channel=bbc
I like to think of resources as the 'thing' i'm returning instead of the standard thinking of relations alone. Underlying in the graph is great for properties, not so sure about collection of 'other things'.
Following the same example, I would rather have /channels/{channel-id}/program instead of /channels/{channel-id}/shows