I try to create a pdf ON Server but what will be the Rest URL? I.e. For a List of all Clubs in one Region GET /clubListForRegion/3
Thanks!
The design of the resource depends on your application domain. If you offer some service for browsing different entertainment branches and you can drill down into certain regions I would propose
GET /regions/north-east/entertainment/clubs
and the representation of this collection of club resources would be a PDF.
If you are offering some service specialised on browsing clubs, you could shorten the hierarchy or use a query parameter:
GET /clubs/techno?region=north-east
If the on the fly creation of the PDF takes a noticeable amount of time, I would propose a POST on the resource instead. The response could contain a link to the final PDF and possibly a link to query the status of the PDF creation process.
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.
Link to the HATEOAS This is the link to the Hateoas article (snapshot below) where the identifiers of the resource is part of the URL i.e. 12345. Here the API response has the final API relative URL i.e. /accounts/12345/deposit and the client just needs to hit it.
Link to the Github Users API This is the link to the Github API (snapshot below) where there are lots of placeholders for identifiers. How will clients modify these URLSs and add a value in these placeholders? For example, {/gist_id}, {/other_user}.
Isn't passing the URL with id value instead of placeholder better? Why and when to rely on different clients to add values in these placeholders?
Hypertext as the engine of application state (HATEOAS) is a bit more than just the usage of links. In essence it enforces the interaction model that is used on the Web for two decades quite successfully. On the web a server usually "teaches" clients (browsers) to achieve something via the help of link relations, that can be used to automatically download related resources or give a hint on the reference resource, and Web forms, that define the syntax and semantics of each of the respective supported (input) elements, i.e. a text field, an option element to select one or multiple choices, a drop down or even a slider widget. Based on the affordance of each of the elements a client knows i.e. that a button wants to be clicked or pressed while a text fields wants some user input and stuff or a link annotated with the prefetch link relation name may be downloaded automatically once the current page finished loading as a client might invoke it next or a preload link relation might instruct a user agent to load the referenced resource early in the current page loading process.
The form not only teaches a client about the supported fields a resource has but also about the target URI to send the request to, the HTTP method to use wile sending the request as well as the media-type, which in the case of Web forms is usually implicitly set to application/x-www-form-urlencoded.
In an ideal world a client just uses the information given by the server. Unfortunately, the world isn't perfect and over time people have come up with plenty of other solutions. Among one of them is URI templating that basically allows clients to use a basic URI and fill out certain placeholders with concrete values. As making use of templating requires some knowledge of the URIs intention or the parameters you need to pass, such capabilities make only sense as part of media-type support.
Plain JSON (application/json) has by default no support for URIs whatsoever and as such a user agent receiving a plain JSON payload might not be able to automatically replace a template URI with a concrete one out of the box. JSON Hyper-Schema (application/schema+json) attempts to add link and URI template support to plain JSON payloads. A user client though needs to be hinted with the appropriate media-type in order to automatically resolve the full URI. As such, the user agent also has to support that respective media type otherwise it won't be able to process the document (resolve the template URI to a real URI) successfully.
JSON Hypertext Application Language a.k.a HAL JSON also supports URI templates for links. application/collection+json does support two kinds of templates - query templates and objects-template. The primer one is similar to a URI template by allowing to append certain query parameters to the target URI upon sending the request while the latter one allows to define a whole object that contains all the input elements used to add or edit an item within the collection. JSON-LD does not really support URI templating AFAIK though it uses the concept of a so called context where certain terms can be used to abbreviate URIs. As such something like name can be used within the context for a URI like http://schema.org/name.
As you can hopefully see, the support for URI templating depends on the media-type used for exchanging data. In the case of the outlined github example GET /users/:username this more or less resembles a typical Web API documentation, similar as it is done in a Swagger API documentation, that unfortunately has hardly anything to do with HATEOAS.
For your top example (banking), you should absolutely include the complete URL, with account numbers (IDs), so that the client does not need to translate/substitute anything. This is the most common scenario with HATEOAS. However, GitHub does have those "placeholders" for endpoints that could contain multiple values. You can't include the "following_url" for every user in the response, it's not practical. So you have to determine the "other_user" value another way and make the substitution. Personally, I haven't even had this use case with any of my applications and all of my HATEOAS URLs resemble you first example (though I prefer full URLs not relative). Unless you have specific cases like GitHub does, it's not necessary to use any of these placeholders. Even GitHub only uses that where they could be multiple values. For fixed value URLs, they have the username (like your account number) in the URL ("octocat").
According to me we should not give the direct url in the body
We should always parameterized the api and get details form there.
In simple case if Id of data change than every time data need to update for detail url.
Else if it’s dynamic you will never face this issue.
And this also come under best practices.
We have listing and details page for mobile, desktop, android and ios?
We have two apis- one for listing and other for details of those listings. So one api is assosiated with other.
listing api looks like:
/api/books/?price=100-300
details api looks like:
/api/book/{bookId}
listing api in response sends back details api link for each listing:
For example:
Request:
/api/books/?price=100-300
will have Response:
{
"books":[
{
"id": 1,
"price": 120,
"pages": 400,
"detailsUrl": "/api/book/{bookId}"
}
]
}
The problem is, should I send detailsUrl with each listing or let all the clients create this? Since they have bookId, they can create it.
What is considered to be best practise considering the url params in details api url may get added in future, api may be versioned and all other possibilities for widely used apis?
I'd put my money on creating the link.
There is a perfect explanation why putting id is not enough
DO NOT include just an entity's ID (such as 12) in a response, because
that way you're forcing clients to put together resource URIs
themselves. In order to do that, they would need to have prior
knowledge of what URIs there are, and you're losing control over the
URI space on the server side.
I recommend to read the entire, linked text (approved answer), it's very detailed and got nice resources. As the author mentioned, there is a popular convention how to make connections between resources - HAL. Consider this instead of detailsUrl.
Even if a link to the resource is obvious right now and you decided to put id alone, in other resources after some time it won't be so simple and you will be forced to specify full URL. Then your API won't be consistent. Experience has taught me it's always easier and better for maintenance to send back full link.
I have a scenario where I have to either
Pull the data from backend as search
Pull the same data from backend to administrate
The URLs I am using are -
/cars
/cars/management
The search can be then subsequently filtered as
/cars?color=blue
The concern that I have is that management is not a resource - it is actually an action. The management page contains links for other functionality associated with car management [add a car/delete a car/list cars/modify cars etc]
Has somebody else faced this issue? Can you let me know your solution?
There is nothing wrong with having a management resource that is a page showing management options for cars. Just because "cars" is the only thing in your database doesn't mean that is the only resource you can present to the user. You could have a resource that is just a form to pick a color (that makes a POST or PUT to the car resource). You could have a resource that is just a form to fill out the address you want the car delivered to. You could have a resource that is just a check box whether you want leather seats or not. You can have as many resources as you like and that make sense, even if all the resources are are pages with forms or links back to the car resource.
Just don't put any verbs in your URLs. You should still be using state transfer using HTTP verbs to change the state of the resources. Don't have a link like
GET /cars/123/deleteCar
on the management page. Instead there might be a link on the management page that (probably using Javascript since browsers have poor native support for HTTP verbs) performs a HTTP request along the lines of
DELETE /cars/123
when the user clicks the link. Something like jQuery can help with that. So long as the management page is using the HTTP verbs to change the state of the resources you are following REST since HTTP is a REST constrained protocol. REST doesn't say don't have actions, it says the actions should be constrained to state transfer.
There is no such concept as a "RESTful URL";
There is no issue with your URLs(/cars, /cars/management)
"/cars/management" is valid resource and it is not an action at all.
The RESTfull way to do this is to use the same URL with different HTTP verbs:
GET /cars for search/listing.
POST /cars for insert.
PUT /cars?id=123 (or /cars/123) for update.
DELETE /cars?id=123 for delete.
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.