How can code be resource?
I will give you an example: I want to create a hotel web site. But also i want to show my customers, which come from abroad, at which time they can come to my city. So i deal with an airplane web site. This site will give me his resources using REST. (resources mean representation of resources). For example his URI will be like that http://example.com/plane/flight%5Fnumber http://example.com/plane/flight%5Fnumber/date
My users will give me a date and i will say them at which flight number they can come. I'll give him a list of flight number then he can fly. OK. there is something i haven't solve yet. if i would know the plane number, i found date. But i dont know which flight number can he travel. So i need to search all the plane and all the flight number to find the same date. But how can i do it? How can i write my query?
another question is I have a function. That function gives me the flight number if i give the date [ int get_Flight_Number(12/11/2009) ].
I just want that clients can see parameters and name of function. And I want him to use my function. How this will be happen?
Without the details of the media types returned by the service it is difficult to answer your question. Does the site return a search form? Does the site return a collection of flights for a set of dates?
The general flow of any http based RESTful client inquiry should go something like this:
Do a HTTP GET on the root url of the
API.
Parse the response based on the
media type specified in the http header "Content-Type".
Does the response contain the answer
to my question?
If yes then extract the information
and do what you want with it.
If no, then does the response
contain a link to another resource
that may have the answer to my
question.
If yes then do a HTTP GET or POST on
that link based on what the media
type definition tells you to do. Goto step 3.
If no then stop looking and tell the
user you cannot find an answer.
Related
I am designing an application that will expose a REST API.
URLs for the resources themselves will look fairly standard, like below:
GET /orders //Get all orders
GET /orders?somefilter=somecriteria //search for orders
GET /orders/<orderid> //specific order
PUT /orders/<orderid> //update a specific order
POST /orders //create an order
My question is regarding resources related to these. I expect the resources will mainly be accessed through an app, but still would like want to provide basic web entry forms, as well as schemas for various resources. What url should they have?
Possible urls
//Option1
GET /forms/orders //new order
GET /forms/orders/<orderid> //edit existing order
GET /schemas/orders
//Option2
GET /orders/form //new order
GET /orders/<orderid>/form //edit existing order
GET /orders/schema
//Option3
GET /orderform //new order
GET /orderform/<orderid> //edit existing order
GET /orderschema
Option 2 doesn't seem right to me, I don't think that the form resource should share the same location on a URL as the order ID. Option 1 looks the best, but would increase the organisational complexity of the app as I couldn't keep the schemas with the rest of the code dealing with a particular resource (but that is a problem that can be solved).
Is there any accepted best practice for these? It does not have to be one of the three options above, any and all pointers would be appreciated.
I am looking for a good URL, following REST principes, to "Move the competitor from team1 to to team2
My first guess is :
/teams/{oldTeamId}/{newTeamId}/competitors/{competitorId}/move
But it doesn't look much like REST.
Should I break it into 2 basics calls ?
Remove competitor from team1,
Add competitor to team2,
Should I remove some data from URL and pass it into the body ?
I don't really know what to do for this one.
Think about how you would implement this API as a web site.
You would probably have a link to a form -- it might be a form where the competitor, old team, and new team are all blank, or it might be a form where the competitor and old team are pre-populated. Your consumer updates the default information in the form as required, and submits it.
Notice the first point (raised by Roman Vottner as well) -- your consumer doesn't need to look at the URL at all. The client knows the HTML form processing rules, so it can create the correct HTTP request without knowing anything about the domain.
The second point is that, since the client is just submitting the form to wherever the HTML tells it to, you can make that anything you want.
One of the interesting properties of HTTP is cache invalidation. See RFC 7234, any non error response to an unsafe request will invalidate all cached representations of one resource.
So you can choose which resource gets invalidated by specifying its URI as the target of the form. In effect, it gives you a mechanism for ensuring that a consumer can read its own writes.
So some reasonable choices for the target might be
/teams/{oldTeamId}
if the team roster is the most important thing. Or
/competitors/{competitorId}
if the resource that describes the player is what is most important.
I don't really know what to do for this one.
Concentrate on make it easy to use. Your resource model is not your domain model is not your data model.
It will likely be useful to watch Jim Webber's talk REST: DDD In the Large to get clearer insights into what your "REST" API should really look like.
To answer your questions, I would not break it into two calls, I would however take some data from that (GET) url and put it in the body of your request. The request would probably be a POST or PUT (or maybe even patch), but definitely not a GET since something is actually changing.
As for a solution, how about a POST request to a /transfer. After all you are (could be) creating a new transfer which takes for example the player, their new team and maybe their old team.
I would use URL to identify the resource which in this case seems to be a competitor's team.
So would
Make the url as /competitors/{competitorId}/teams
Make the call PUT
Have a body with newTeamId and if required the oldTeamId.
Could somebody help to find out the expected behavior in filtering data within REST.
I have an ordinary REST-service with API
GET /api/articles <-- extract all articles
GET /api/articles?category=1 <-- extract all articles belonging the
particular category
I have doubts regarding the second stuff. What must a request return if user set an invalid category. There're 3 options:
return all articles
return an empty collection
return error
I suppose that it might be up to me, but anyway I wonder whether somebody have implemented this and how he/she resolved it.
You have answered your question yourself, but to provide you an example how this is already implemented (in numerous cases) but just pointing to one such example using JIRA.
You can use JIRA's REST APIs to GET the ticket details and which is what I'm showing you here:
Using CURL, I've tried to get the ticket details providing an invalid JIRA ticket id and the above is the response that I received.
It is up to us to decide upon what needs to be the outcome of the REST APIs that we develop, just pointing out one of the scenarios from JIRA REST APIs where they chose to error out (instead of showing no response or etc).
Hope this answers your question well!
So the application is for a warehouse and you need to retrieve all of the products in the warehouse created by a particular client. What would a URI that is RESTful look like to accomodate this?
Here are some ideas that I had:
/Product/Client/[the client's ID]
/Product?clientID=[the client's ID]
What would a RESTful URI for this scenario look like?
From my point of understanding, first one is better options. In first scenario, you will only check the route from the URI and client id will be in the body param. In the second scenario, you are adding clientsID in the header. Although I am not a master but what saw the way people write, they follow the first option. You might get an idea from here: http://www.restapitutorial.com/lessons/restfulresourcenaming.html
Wait for the response from master in that area. thanks
You're identifying a specific client, so start with
/Client/[Client ID]
and then specify a resource "belonging to" that client
/Client/[Client ID]/Products
It all depends on the use case for this requirement.
If the client would usually navigate to a client, and then needs to view its products, then as #esorf said:
/client/{clientId}/products
However, if the client is displaying products for various clients (albeit only one at a time), something like this might make more sense:
/products?clientId={clientId}
This latter one could also be extended to use URI Templates in order display products of more than one client like so:
/products{?clientId*}
which expands into
/products?clientId={clientId1}&clientId={clientId2}
Consider the following scenario:
There are two existing entity: shopping card #1 and item #1. I want to add item #1 to shopping card #1. There are two possible ways to design a Restful api:
1:
Without body:
PUT http://myshoppingsite.com/api/shoppingcards/1/items/1
Host: myshoppingsite.com
2: With body (having enclosed-entity):
PUT http://myshoppingsite.com/api/shoppingcards/1/items/
Host: myshoppingsite.com
{itemId: "1"}
Actually, I cannot decide which one is better and is more meaningful in terms of restfulness. Any idea?
(Note: I believe the http method should be PUT because of idempotency, but this is not my question here.)
PS: The problem I have with the first design is that there is no such enclosed entity in the request. Linguistically put is a transitive verb, so I expect somebody puts something somewhere. I think the same story somehow is in the HTTP world.
PUT is a HTTP verb that is supposed to create or replace the target URI, so this makes your first option immediately wrong. This request should replace all the items in your shopping cart:
PUT http://myshoppingsite.com/api/shoppingcards/1/items/
Since you want to add something to your shopping cart, this is not an option. This leaves effectively two options. First: the common one:
POST http://myshoppingsite.com/api/shoppingcards/1/items/
POST can mean many things, but in the context of REST services it's often used to append something to a collection. However, you mention that you want idempotence. You have two options here, first you can still use POST and within the context of your API guarantee that the request will be idempotent. Using POST does not mean that it's per definition non-idempotent, it just means that the HTTP spec alone does not guarantee it. That does not prevent you from making the request idempotent.
The other option is indeed PUT:
PUT http://myshoppingsite.com/api/shoppingcards/1/items/1
Your have a concern with that though, because in the context of your API you say that the request body would end up empty.
The reason for this is that you attach special to the last /1 in the url, and I think this what's wrong. If you want to follow REST best practices, then urls should not have any special meaning.
I think a saner way to do this, if you insist on using PUT is to get rid of the notion of "an id". That concept only exists in your database and should not make its way to the API.
Instead, I imagine that your service has a list of products such as this one:
http://myshoppingsite.com/products/1
To add a product to a shopping cart using PUT, this request might look something like this:
PUT http://myshoppingsite/api/shoppingcards/1/items/[completely-arbitrary-string-or-perhaps-a-uuid]
Content-Type: application/json
{
"product" : "http://myshoppingsite.com/products/1",
"quantity" : 5
}
Personally, I would just use POST though.
Q: there should be some information about the product you are addisng, no? Yes and that information is part of Uril. Why is it bad?
I'm not saying it's bad, I'm saying it's not RESTful. Pick up any book about REST and you will see this confirmed. This might also be a good place to start reading more about what REST is:
http://martinfowler.com/articles/richardsonMaturityModel.html
I would personally say that very little people build true RESTful services. This is why I also want to specifically point out that I don't want to say this is bad or good for your specific API, it's simply not RESTful.
What if I don't care about these principles and want to keep my special-meaning url scheme?
Well that's a fair point, but then we've gone beyond the original question here. If you want to design an API where the last bit of the url is actually the 'representation' of the item in your shopping cart, then yes I agree that having it also in the body is redundant.
In that situation I'd say, keep the request body empty. Just don't call it REST I guess.