I've looked at the documentation for creating profiles for FHIR, and I've used Forge to create some xml that I believe is valid to describe a profile. I can't find in the documentation where it actually states what request I need to make to the RESTful api to actually add a new profile.
Any ideas?
You can of course just "store" your profiles on a FHIR server by POSTing them to a FHIR endpoint, but you probably mean: can I actively let instances be validated against the StructureDefinition?
There are two ways, both of which require a bit of experimentation to see which public servers support them:
Any FHIR instance may declare it adheres to a StructureDefinition, by adding the canononical url (StructureDefinition.url) to the instances meta.profile as shown below. Servers may pick this up on a POST and validate the instance against the stated profile:
<Patient>
<id value="44Q3"/>
<meta>
<profile value="http://example.org/StructureDefinition/PatientNL"/>
</meta>
</Patient>
Actively ask a server to validate your instance using the $validate FHIR operation (see http://hl7.org/fhir/resource-operations.html#validate)
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.
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 need to design an operation “duplicate” for "articles".
My thought was: a POST on apibaseurl/articles/{id}/duplicates and returning a 200 OK with the URI of the created duplicate, which's URI however will conform to the template apibaseurl/articles/{id}.
When issuing a GET to apibaseurl/articles/{id}/duplicates however, there will not necessarily be a list of duplicates (meaning: the server will not keep track of all duplicates created for an article - the "duplicate" relationship is ignored by the server outside the scope of the request)
Questions:
is my suggested solution OK?
does it not violate any RESTful principle by having the URI of the created object point to a location not under the resource under which it was posted?
would I have to provide a client with the possibility to list all duplicates for an article?
is my suggested solution OK?
It looks fine to me.
does it not violate any RESTful principle by having the URI of the created object point to a location not under the resource under which it was posted?
No, that is not necessary. You POST to a collection resource but this does not force you to return a Location header pointing inside this collection.
would I have to provide a client with the possibility to list all duplicates for an article?
If you have a use case for this, you could provide it. But if there is no business interest in listing the articles created as duplicates of an existing article, you don't have to.
Go ahead :)
I am trying to build a little web application with the MEAN stack (MongoDB, ExpressJS, AngularJS and NodeJS).
My question is very simple. If you take the example of a blog, it will contains blog posts, that you could list at this url:
GET /api/posts
You could also get the comments for that posts:
GET /api/posts/:postId/comments
and get a single comment:
GET /api/posts/:postId/comments/:commentId
The relation between post and comment is really obvious here, but does it still makes it mandatory to have it this way? or could I just perform my CRUD operations through /api/comments? In the end, a comment object in mongodb will always have a postId attribute anyway which will reference the post that it is related to... Moreover, the API will not be exposed and is strictly meant to be used by the application.
does it still makes it mandatory to have it this way?
No. This is not mandatory at all.
or could I just perform my CRUD operations through /api/comments?
Yes. This will result in cleaner resources URIs (endpoints).
You can also get post-specific comments with:
GET /api/comments?postId={postId}
Further, you could also drop the /api prefix if you are serving only an API at the given host.
I want to give everyone who subscribes to a node the ability to both read and write to that node.
Joe created the node "test5" in the code below. When Mark tries to post, I get an error.
I am using XMPPFramework for iphone. I receive the following error IQ. It appears that openfire is telling me that I can't publish an item b/c I don't have access? What is the default access model, open?
Doesn't that mean that anyone can subscribe to the node "test5", and anyone can publish items to it?
The JID of the fake user who originally created node "tes5" is "mark#joes-macbook-air.local"
Could the unauthorized message posting be b/c mark is not the owner of node titled "test5"?
What if I want mark to be able to post to this feed as well?
<iq xmlns="jabber:client" type="error" from="pubsub.joes-macbook-air.local" to="joe#joes-macbook-air.local/838f75ba"><pubsub xmlns="http://jabber.org/protocol/pubsub">
<publish node="test5"><item><body>Helpl me</body></item></publish>
</pubsub><error code="403" type="auth">
<forbidden xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"/>
</error>
</iq>
Update: I made the subscriber a "publisher". This is done by altering the publish_model of the node.
This depends on the node configurations in your pubsub service. Particularly the access mode of your node. In the XEP-0060 the access models section gives a good explanation on the different access methods. (1) The one you need in your case will be the "Open" which is defined as "Any entity may subscribe to the node (i.e., without the necessity for subscription approval) and any entity may retrieve items from the node (i.e., without being subscribed); this SHOULD be the default access model for generic pubsub services."
I hope this gives a clear answer to your question.