Lets say I am designing a Restful service which given 2 integer no.'s returns the sum of it.
In this case there is no resource to be read, created, updated or deleted.
So, if I design something like GET /sum/first/33/second/44, it doesn't comply with the REST standards as 'sum' is a verb and instead there should be a noun representing the resource name.
So, how should the API call look like for invoking the sum.
Please help me with the design.
Use "summation" instead of "sum" if your concern is noun vs. verb. As far as parameters are concerned, I think you should supply all the numbers you want to sum up together for eg. /summation/1,2,3,4 or /summation/1+2+3+4.
REST says nothing about what your URLs should look like. You can honestly have anything you want: GET /hdueqixp returning "77", for example.
Me, I like short, self-explanitory URIs. I would use /sum/33+44. You're not including action parameters in the request URL, so don't worry about verbs vs. nouns. That is for people still doing things like GET /users/deepak?action=delete and expecing the resource to be deleted.
Related
I have $dinetype variable obtained from the user.
But I would like to give response based on what value has been set in $dinetype variable. In addition to giving responses, I also need to set relevant context. How do I do this in DialogFlow?
if($Dinetype=='dineout')
ask ('which restaurant would you like to go to?')
set_context ('awaiting-restaurant')
if($Dinetype=='takeaway')
ask ('When would you like to take away?')
set_context ('awaiting-takeaway-time')
Is it programmable at all? Or is it possible to achieve something equivalent to the above in the UI?
Edit: A much easier way has been added to handle this issue directly in Dialogflow
(Updated Solution) Follow-up Intents:
After creating an intent, you can add follow-up intents now.
Intents -> Create Intent >
[Response=Prompt For Conditional Response]
Intents -> Add Follow-up Intent -> Custom/Yes/No
Then set the training praise to a matching entity you want to conditionally respond to
OLD HACKY SOLUTION:
Late reply, but maybe someone will find this useful.
If the conditional response only needs to reference a single parameter
value, then I figured out what you can do is utilize the Entity's
"Reference Value" as the response you want to give for a particular
set of Synonyms.
So you'd have an entity that looked like this:
Then, setup your intent like this, with a response of $Dinetype:
Then the end result will look like this:
And you can make whatever follow-up intent you need from there.
Down-side is Dinetype won't be as reusable. But I still think it
beats writing a fulfillment webhook every time you need a simple
conditional response.
You can't do this in the Response section directly. The Response section is meant for fairly simple responses that don't require significant logic to process. Although you can use parameters in the response, you can't give a different response based on the value of the parameter. So you can set a response to something like
I think $Dinetype is great food.
but not
{{#if $Dinetype == "Thai"}}I think Thai food is too hot{{/if}}
or anything like that
However, you can add code that sends conditional responses and contexts by implementing a Fulfillment webhook. Although you can't do this for each Intent as part of the Intent editor screen, the Fulfillment screen includes a built-in code editor.
I found a solution to my similar problem using composite entities, which may or may not be overkill for your agent. The value assigned to a parameter associated with the (composite) entity will contain a JSON structure, if a synonym in that entity was matched.
Using the "Dot" notation, you can assign the matched sub-entity's property (similar to the reference value of a normal entity) to another parameter in the Actions and Parameters section. You can have one parameter for each sub-entity and hence, you can evaluate these parameters in your response section to select each response variants:
$Parameter_A ResponseA
$Parameter_B ResonseB
....
etc.
Clunky but works. Just have to be careful to reference the property exactly as it is defined in the composite entity.
I need to create a RESTful webservice that allows for addressing entities by using different types of IDs. I will give you an example based on books (which is not what I need to process but I want to build a common understanding this way).
Books can be identifier by:
ISBN 13
ID
title
I can create a book by POSTing to /api/v1/books/The%20Bible. This book can then later be addressed by its ISBN /api/v1/books/12312312301 or ID /api/v1/books/A9471IZ1. If I implemented it this way I would need to analyze whatever identifier gets sent and convert it internally.
Is it 'legal' to add the type of identifier to the URL ? Like /api/v1/books/title/The%20Bible?
It seems that what you need is not simply retrieving resources, but searching for them by certain criteria (in your case, by ISBN, title or ID). In that case, rather than complicate your /books endpoint (which, ideally, should only returns books by ID), I'd create a separate /search function. You can then use it search for books by any field.
For example, you would have:
GET /search?title=bible
GET /search?isbn=12312312301
It can even be easily expanded to add more fields later on.
First: A RESTful URl should only contain nouns and not verbs. You can find a lot of best-practices online, as example: RESTful API Design: nouns are good, verbs are bad
One approach would be to detect the id/identifier in code.
The pattern would be, as you already mentioned:
GET /api/v1/books/{id}, like /api/v1/books/12312312301 or /api/v1/books/The%20Bible
Another approach, similar to this.lau_, would be with a query parameter. But I suggest to add the query parameter to the books URL (because only nouns, no verbs):
GET /api/v1/books?isbn=12312312301
The better solution? Not sure…
Because you are selecting “one book by id” (except title), rather than performing a query/search, I prefer the first approach (…/books should return “a collection of books” and .../books/{id} should return only one book).
But maybe someone has a better approach/idea?
Edit:
I suggest to avoid adding the identifier to the URL, it has “bad smell”. But is also a possible approach and I saw that a lot in other APIs. Let’s see if I can find some information on that, if its “ok” or should be avoided.
Edit 2:
See REST API DESIGN - Getting a resource through REST with different parameters but same url pattern and REST - supporting multiple possible identifiers
I understand how to use REST for doing general entity interactions - using urls names to map to entities and the HTTP verbs to map to actions on those entities. But what is the generally accepted way of looking at "actions" more like RPC?
For example, let's say I want to send a command for the device to reset? There's no real "entity" here or do I do something like POST to http://mydevice/device/reset?
/device/reset or /system/reset are ok.
The REST "design pattern" does encourage you to NOT use any verbs.. You could do:
POST http://mydevice/system/state
<stateType>RESET</stateType>
Related information:
How to create REST URL’s without verbs?
Threads tagged with restful-url
I don't think that's the case to use POST. The "RESET action" is a idempotent action (if you call it n times you will always get the same result), so IMHO you should use a PUT call instead POST (as POST is not idempotent).
Also, as you are Putting a resource, you can use
PUT http://system
<device>
<status>RESET</status>
</device>
or
PUT http://system/status/reset
But I think the first one is "more restful", since you are putting a resource, while the second one you just use the URL.
I usually name the entity "system" or something like that. So you do "/system/reset". You've chosen device so that works too.
But yea, I usually consider these types of actions to be updates, which would use the POST method. So I think you are right to POST to /device/reset
Let's say I have a method that returns a list of customers and as input has a list of states and list of sizes, something like
return customers where state in (NY, CA, TX) and size in (Small, Medium)
What would the best RESTFul URL that I should use? The problem that it is a query and does not point to a specific 'resource'. Here are some options that I am mulling over.
somesite.com/customers?state=NY,CA,TX&size=small,medium (old style)
somesite.com/customers/state/NY,CA,TX/size/small,medium
somesite.com/customers/state=NY,CA,TX/size=small,medium
somesite.com/customers/state(NY,CA,TX)/size(small,medium)
Option 1 - query params are intended for exactly that. Parameters for your query.
You are interested in a list of customers therefore the last "folder" should be "/customers". The fact that you want a subset of these and that that subset is variant depending on input, and in combination leads you to query params acting as filters. (Nothing else would make sense as you see by being compelled to ask the question).
The real question you have is whether the params are going to be inclusive or exclusive by default (i.e. AND or OR). That question has already been asked here if I can just find it...
I think #1 (somesite.com/customers?state=NY,CA,TX&size=small,medium) is the best of the bunch. The customers are the resources, and the query string is just placing restrictions on the resources being requested.
Personally, I'd use the 4th approach, but with the '+' sign instead of parenthesis:
somesite.com/customers/NY+CA+TX/small+medium
RESTful-style your Models are not necessarily all the RESTful Resources you should offer... You can add any number of (artificial) resources as you see fit, even ones that would require a JOINs from your Models.
For what it's worth, URI naming conventions has nothing to do with REST. In fact, if you define a way of constructing your application's URIs out-of-band as part of your API, you are violating a constraint of REST. See: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
This is one of those little detail (and possibly religious) questions. Let's assume we're constructing a REST architecture, and for definiteness lets assume the service needs three parameters, x, y, and z. Reading the various works about REST, it would seem that this should be expressed as a URI like
http://myservice.example.com/service/ x / y / z
Having written a lot of CGIs in the past, it seems about as natural to express this
http://myservice.example.com/service?x=val,y=val,z=val
Is there any particular reason to prefer the all-slashes form?
The reason is small but here it is.
Cool URI's Don't Change.
The http://myservice.example.com/resource/x/y/z/ form makes a claim in front of God and everybody that this is the path to a specific resource.
Note that I changed the name. There may be a service involved, but the REST principle is that you're describing a specific web resource, named /x/y/z/.
The http://myservice.example.com/service?x=val,y=val,z=val form doesn't make as strong a claim. It says there's a piece of code named service that will try to do some sort of query. No guarantees.
Query parameters are rarely "cool". Take a look at the Google Chart API. Should that use a /full/path/notation for all of the fields? Would each URL be cool if it did?
Query parameters are useful. Optional fields can be omitted. New keys can be added to support new functionality. Over time, old fields can be deprecated and removed. Doing this is clumsier with a /path/notation .
Quoting from http://www.xml.com/pub/a/2004/08/11/rest.html
URI Opacity [BP]
The creator of a URI decides the encoding
of the URI, and users should not derive
metadata from the URI itself. URI opacity
only applies to the path of a URI. The
query string and fragment have special
meaning that can be understood by users.
There must be a shared vocabulary between
a service and its consumers.
This sounds like query strings are what you want.
One downside to query strings is that the are unordered. The GET ending with "?x=1&y=2" is different than that ending with "?y=2&x=1". This means the browser and any other intermediate systems won't be able to cache it, because caching is done based on the full URL. If this is a concern, then generate the query string in a well-defined order.
While constructing URIs this is the priniciple I follow. I don't know whether it is perfectly acceptable in all cases
Say for instance, that I have to get the details of an employee, then the URI will be of the form:
GET /employees/1/ and not GET /employees?id=1 since I treat every employee as a resource and the whole URI "employees/{id}" is used in identification of the resource.
On the other hand, if I have algorithmic operations that do not identify a specific resource as such,but merely require inputs to the algorithm which in turn identify the resource, then I use query strings.
For instance GET /employees?empname='%Bob%'&maxResults=100 might give me all employees whose names have the word Bob in them, with the maximum results returned by the query limited to 100.
Hope this answers your question
URIs are strictly split into a hierarchical part (the path) and a non-hierarchical path (the query), and both serve to identify the resource
Tthe URI spec itself (RFC 3986) clearly sets the path and the query portion of a URI as equal.
Section 3.3:
The path component contains data [...] that along with [the] query component
serves to identify a resource.
Section 3.4:
The query component contains [...] data that, along with
[...] the path component serves to identify a resource
So your choice in using x/y/z versus x=val&y=val&z=val has mainly to do if x, y or z are hierarchical in nature or if they're non-hierarchical, and if you can perceive them as always being hierarchical or non-hierarchical for the foreseeable future, along with any technical limitations you might be having on selecting one over the other.
But to answer your question, as others have noted: Neither is more RESTful than the other, since they both end up identifying a resource.
If the resource is the service, independent of parameters, it should be
http://myservice.example.com/service?x=val&y=val&z=val
This is a GET query. One of the principles behind REST is that you GET to read (but not modify!) the resource; you can POST to modify a resource & get a response; you can PUT to write to a resource; and you can DELETE to remove a resource.
If the resource specific with those parameters is a persistent resource, it needs a name. You could (if you organized your webservice this way) POST to http://myservice.example.com/service?x=val&y=val&z=val to create a particular instance of the service and have it return an ID to name this instance, e.g.
http://myservice.example.com/service/12312549
then use GET/POST/PUT/DELETE to interact with that instance.
First of all, defining URIs as part of your API violates a constraint of the REST architecture. You cannot do that and call your API RESTful.
Secondly, the reason query parameters are bad for non-query resource access is that they are generally not cached. It is also a violation of HTTP standards.
A URL with slashes like /x/y/z/ would impose a hierarchy and is not suited for the exact case of just passing three parameters.
If, like you said, x y z are indeed just parameters and the order is not important, it would be more RESTful to use semicolons:
http://myservice.example.com/service/x;y;z/
If your "service" however is just an algorithm that works the same with different parameters, there would also be nothing unRESTful with using ?x=val format.