I was not able to get clarity on the naming convention to follow on google protobuf naming convention documentation. Hence thought to reach out to community to know what should be the method, request & response naming
If i have something that fetches list of student using studentIds, should i name my method
rpc StudentByIdList(StudentByIdListRequest) returns (StudentByIdResponse)
or
rpc ListStudent(StudentIdsRequest) returns (StudentResponse)
or something else
The 2nd one doesn't seem right because in case i have more than 1 method which fetches students by name starting with and student ids.
I went through the google protobuf naming convention documentation and i did find that preposition is not allowed, so By in the method name is wrong, but how do we represent in method that i want to find Student List of Student Id's
I don't know whether there is a documented convention.
The style guide is brief.
If I were implementing your solution, I would 'encode' the difference between the 2+ methods in the request message:
rpc ListStudents(ListStudentsRequest) returns (ListStudentsResponse)
ListStudentsRequest would include a oneof (id,name) or, more commonly and more extensibly a filter field in which constraints could be specified (as a string). This mechanism permits the inclusion of e.g. paging too.
Google has a Google APIs repo that documents its services that support gRPC.
You can review the protos files in the google subdirectory to see how Google solves this problem.
The proto for Google Cloud Storage includes List methods for the various resources in the service.
For ListBucketsRequest you can see a prefix field that's used to filter the results.
Related
I like the idea of vectorized/batched requests similar to what the StackExchange API offers and would like to implement something for my own API, i.e. GET /users/1;2;3;4;5 would return the selected user resources with id 1 to 5.
I think this is fairly simple when reading data, but what would be the expected behavior for i.e. a POST request to a subresource?
POST /1;2;3;4;5/subresource
Would this mean:
Creation of five new subresources, assigned to each id (1:1)
Creation of a single new subresource, but assigned to each resource id (1:n)
I have a couple of concerns regarding this approach. First, resources should be uniquely addressable via certain resource locators (URIs). Using your approach however bypasses this requirement in some way IMO. This approach may also lead to other issues later on, i.e. plenty of frameworks do not allow URIs that exceed a certain character size.
Furthermore, instead of consecutive resource IDs the resource should use UUIDs instead. This will first and foremost prevent guessing attacks and also prevent logical issues on moving resources or inserting some in between.
The POST method requests that the target resource process the
representation enclosed in the request according to the resource's
own specific semantics.
In regards to HTTP POST operations, the specification clearly states that the semantics of any body received via POST is up to the service developer. So you are basically allowed to do anything within a POST request. As the semantics is totally up to you, you have to document the behavior explicitely. Not documenting the applied logic will leave a large grey-zone for service users.
All, Forgive me I am a newbie in the DICOM world. I tried to learn the DCMTk tools to talk with PACS server. But didn't found much tutorial or sample in the internet to know enough about it .Currently I just have the offical document to read.
I just tried the findscu.exe to test c-find command .
I remembered C-Find would return what specified in the request message. for example. If I only specifed the condition Patient Name ='abc' then the reponse would return only attribute Patient Name. Nothing else.( If it is not right . Please correct me.)
So I want to know how to return all the attribute of response DICOM.
Thanks.
How to specified multiple attributes in the findscu command.
Just specify multiple --key (-k) options on the command line. Alternatively, you could also use a "query file" as described in the man page.
So I want to know how to return all the attribute of response DICOM.
Then, you have to specify all attributes (keys) you are interested in. That's how C-FIND works.
By the way, if you are querying a PACS (Query/Retrieve SCP), then you also have to specify the Query/Retrieve Level (0008,0052), e.g. "PATIENT".
Currently I just have the offical document to read.
If you think that the examples in the man page of the findscu tool are not sufficient (and you are actually querying a PACS), this HOWTO might be useful too.
It is totally legal to send a request with Patient Name information only and the PACS will return all matching datasets.
Each dataset should at least contain all mandatory fields like Date of Birth, Patient ID, and so on, depending on the Query Level.
What information is returned by the PACS system on each Query Level should be specified in the DICOM Conformance Statement of the vendor. I would recommend to take a look at this to know, how to set up a valid query to get the information you need and/or if the information is provided by the PACS system.
It is best to include the Unique key and Required Key Attributes in the request attribute list. Also, include the optional attributes (if supported by SCP) when you wish server to return values for them. Please refer to DICOM Standard PS 3.4 section C.2 and C.3 detail information on Query/Retrieve service. List of attribute and type (Unique, Required, Optional) is listed section C.6.1.1.2 (Patient Level), C.6.1.1.3 (Study Level) and so on.
I am attempting to develop a Freebase Explorer application. one part of the application allows a user to drill down through freebase Domains, then types then type instances, then finally using the freebase Topic API i display the selected Type Instance. however many of the type instances lists do have "null" for the name and machine ids for the id.
what combination of freebase api calls can i employ to return something of value/interest (man readable) using a freebase mid?
where should i look in the freebase site/wiki to help?
A machine ID (MID) can be used anywhere any other ID is used in Freebase. There's no requirement that an object have a name. "Something of value/interest" will depend a lot on the context, but the types and property values of an object help show how it's connected to the rest of the graph.
You might also look at the existing Freebase Schema Explorer app for ideas and inspiration.
Tom's explanation regarding machine ids is spot on, here is some additional information:
Domains and types are schema objects and it's preferable that you use human readable ids for these. Items "of interest" are usually topics, and those are all objects that are typed with /common/topic.
You can use MQL to get a list of types and domains, and then as you say use the Topic API - which will also be available in the new APIs - to get all the data for a given topic.
I have come across this issue a few times now, and each time I make a fruitless search to come up with a satisfying answer.
We have a collection resource which returns a representation of the member URIs, as well as a Link header field with the same URIs (and a custom relation type). Often we find that we need specific data from each member in the collection.
At one extreme, we can have the collection return nothing but the member URIs; the client must then query each URI in turn to determine the required data from each member.
At the other extreme, we return all of the details we might want on the collection. Neither of these is perfect; the first can result in a large number of API calls, and the second may return a lot of potentially unneeded information.
Of the two extremes I favour the second in our case, since we rarely use this for more than one sutiation. However, for a more general approach, I wondered if anyone had a nice way of dynamically specifying which details should be included for each member of the collection? I guess a query string parameter would be most appropriate, but I don't want to break the self-descriptiveness of the resource.
I prefer your first option..
At one extreme, we can have the
collection return nothing but the
member URIs; the client must then
query each URI in turn to determine
the required data from each member.
If you are wanting to reduce the number of HTTP calls over the wire, for example calling a service from a handset app (iOS/Android). You can include an additional header to include the child resources:
X-Aggregate-Resources-Depth: 2
Your server side code will have to aggregate the resources to the desired depth.
Sounds like you're trying to reinvent PROPFIND (RFC 4918, Section 9.1).
I regularly contain a subset of elements in each item within a collection resource. How you define the different subsets is really up to you. Whether you do,
/mycollectionwithjustlinks
/mycollectionwithsubsetA
/mycollectionwithsubsetB
or you use query strings
/mycollection?itemfields=foo,bar,baz
either way they are all different resources. I'm not sure why you believe this is affecting the self-descriptive constraint.
I'm well into implementing a REST service (on a Windows CE platform if that matters) and I started out using IBM's general definitions of using POST for creating (INSERTs) and PUT for updating.
Now I've run across Sun's definitions which are exactly the opposite. So my question is, which is the "generally accepted" definition? Or is there even one?
The disadvantage of using PUT to create resources is that the client has to provide the
unique ID that represents the object it is creating. While it usually possible for the client
to generate this unique ID, most application designers prefer that their servers (usually
through their databases) create this ID. In most cases we want
our server to control the generation of resource IDs. So what do we do? We can switch
to using POST instead of PUT.
So:
Put = UPDATE
Post = INSERT
The reason to use POST as INSERT and PUT as UPDATE is that POST is the only nonidempotent and unsafe operation according to HTTP. Idempotent means that no matter how many times you apply the operation, the result is always the same. In SQL INSERT is the only nonidempotent operation so it should be mapped onto POST. UPDATE is idempotent so it can be mapped on PUT. It means that the same PUT/UPDATE operation may be applied more than one time but only first will change state of our system/database.
Thus using PUT for INSERT will broke HTTP semantic viz requirement that PUT operation must be idempotent.
The verbs are:
GET {path}: Retrieve the resource whose identifier is {path}.
PUT {path}: Create or update the resource whose identifier is {path}.
DELETE {path}: Delete the resource whose identifier is {path}.
POST {path}: Invoke an action which is identified by {path}.
When the intention is to create a new resource, we can use PUT if we know what the identifier of the resource should be, and we can use POST if we want the server to determine the identifier of the new resource.
PUT can be used for creation when the server grants the client control over a portion of its URI space. This is equivalent to file creation in a file system: when you save to a file that does not yet exist you create it and if that file exists the result is an update.
However, PUT is lacking the ability of an implicit intent of the client. Consider placing an order: if you PUT to /orders/my-new-order the meaning can only ever be update the resource identified by /orders/my-new-order whereas POST /orders/ can mean 'place a new order' if the POST accepting resource has the appropriate semantics.
IOW, if you want to achieve anything as a side effect of the creation of the new resource you must use POST.
Jan
We use POST= Create, PUT= Update.
Why? There's no good reason. We had to choose one, and that's that choice I made.
Edit. Looking at other answers, I realize that the key creation issue might make the decision.
We POST new entries and return a JSON object with the generated key. It seems like this is a better fit for generally accepted POST semantics.
We PUT to existing entries with a full URI that identifies the object.
Here http://www.w3.org/Protocols/rfc2616/rfc2616.html is the offical guide of how to implement the behaviour of the HTTP methods.
I've been studying the concepts and implementations of REST a lot lately and the general consensus seems to be: PUT is used for creating/updating depending on whether or not the resource already exists. POST is used to append a resource to a collection.
See HTTP/1.1 Method Definitions http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
POST is designed to allow a uniform method to cover the following
functions:
- Annotation of existing resources;
- Posting a message to a bulletin board, newsgroup, mailing
list, or similar group of articles;
- Providing a block of data, such as the result of submitting a
form, to a data-handling process;
- Extending a database through an append operation.
The PUT method requests that the enclosed entity be stored under the
supplied Request-URI. If the Request-URI refers to an already existing
resource, the enclosed entity SHOULD be considered as a modified
version of the one residing on the origin server.
Also see the accepted answer to the question at Understanding REST: Verbs, error codes, and authentication.