I have reviewed RFC2616. For a "406" it states:
Unless it was a HEAD request, the response SHOULD include an entity containing a list of available entity characteristics and location(s) from which the user or user agent can choose the one most appropriate. The entity format is specified by the media type given in the Content-Type header field. Depending upon the format and the capabilities of the user agent, selection of the most appropriate choice MAY be performed automatically.
But, I'm a little confused about what to return and how. For example, if I have a RESTful'ish resource that can only return JSON, and the accept header specifics that the caller only wants XML, how should I tell him that I can only return JSON?
I think it's safe to respond with a list of the available content types using the Content-Type the resource provides - in your case Json.
It's kind of a "best-effort" approach of the service and it's the responsibility of the client to react to the problem or abandon the request.
For example if you travel abroad (i.e. to Germany) and go to the local butcher. You only speak English and the butcher only speaks German and French. You ask in English for Beef.
Because the butcher doesn't understand you, he responds in German and French asking you to change the language of your request ("Sprechen Sie deutsch?", "Parlez vous Francais?").
Now it's your choice to:
- learn German or French ("Rindfleisch", "Boef")
- try another common language (handsigns, primeval sounds)
- leave and search for a butcher that understands English
Related
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.
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.
I want to know in my fulfillment what was the language the user was spoken when the intent was triggered.
Is there a way to know that? I didn't find that information in the request header or in the request data.
Thanks
Guzman
This information is part of the user locale and is part of the JSON body that is sent. You can get this in one of a few ways:
If you're using the node.js library, you can use app.getUserLocale()
If you're using the Action SDK, this is in the JSON at user.locale
If you're using Dialogflow, this is in the JSON at originalRequest.data.user.locale
In each case, the value returned will be something like en-US specifying the language and locale the user is using.
Keep in mind that you will still need to register your Action to handle these languages or language/locale pairs in the Action console.
I have set a simple template DocuSign for my client.
I use this template to send request signature with the REST API.
The body and the object mail are been modified in the request :
{
[...]
"emailSubject" : "Document à signer",
"emailBlurb" : "Merci.",
[...]
}
But, for now, the e-mail are in English.. Can I change the language on French ?
I read it is possible to personalize the language of each recipient but for that, I must modify the request.
Is it possible to change the language without personalize the language of each recipient
Thanks in advance,
Frédéric.
Please search for previously asked questions under the #DocuSignAPI tag as this has been answered before. Take a look at the API Documentation in the Developer Center and do a search for emailNotification. You'll see how to set language through there.
Take a look at this previous post:
Embedded DocuSign signing: using recipient's language
You should also take a look at the Signer Resource File which allows additional language settings.
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.