The documentation for canonical states that it is "is a special kind of Business Identifier" but then goes on to say "The canonical URL serves as a stable logical identifier for the resource". I understand the difference between the two types of identifiers, but it's unclear to me which I am suppose to use for canonicals.
The canonical identifier is the stable URI assigned by the source of truth which is the sole mechanism of referencing the resource via the canonical data type - which is the primary mechanism of referencing canonical resources. It is a 'logical' identifier in that there is no requirement for it to resolve (though it's nice if it does). It is a 'business' identifier in that it can be shared by different instances on different servers and always refers to the same business object and isn't expected to have any correlation to the resource identifier of the instance on any given server.
Related
As far as I know, POST is usually used for changing the state of the server, and PUT usually for updating the information. If I am creating a new index, should it not be POST instead of PUT? PUT does make sense when creating a document as it changes the state of data.
Your statement
As far as I know, POST is usually used for changing the state of the server, and PUT usually for updating the information.
does conform to the conventional HTTP vs CRUD semantics:
HTTP method
CRUD equivalent
Description
POST
Create
Let the target resource process the representation enclosed in the request.
PUT
Update
Set the target resource’s state to the state defined by the representation enclosed in the request.
However, the PUT spec also stipulates that:
The PUT method requests that the state of the target resource be
created or replaced with the state defined by the representation
enclosed in the request message payload
As such, PUT can (and is) used in Elasticsearch to both create an index AND update its
[settings and mappings].
Also, keep in mind that it's rarely just a matter of strict adherence to the semantics. One of the creators of ES put it this way:
It's all about REST semantics.
And our understanding of the semantics at the time when we made the APIs. And backwards compatibility constraints. And whatever "feels" natural to the person who implemented the API.
Where it makes a lot of sense Elasticsearch maps the HTTP verbs to
useful things. But when it doesn't make a ton of sense we just go with
whatever verb feels good rather than trying to be super strict about
REST. Also, we don't do linked data, instead relying on you to build
links from context. I'm told that is particularly non-REST. But it is
what we do.
The Resource entity define an id attribute as "Logical id of this artifact". Meanwhile for resources like MedicationRequest also define an attribute named identifier. The description is "External identifier" or "Business identifier".
I'm wondering what's the difference between these two attributes? From the RESTful API definition like update, the id can be used to uniquely locate the resource, like POST [base]/[resource]/[id]. After POST another GET should be able to retrieve that resource using GET [base]/[resource]/[id]. It's more like something similar to a storage identifier. Then how about that identifier?
the .id is controlled by the local server. As a resource is coped from server to server, it will change. it's basically the internal primary key for the object, and it's entirely controlled by the FHIR server itself (or, more precisely, by the interaction between the client and server). So it's not a portable identifier.
But almost all the resources correspond to (somewhat) real world entities that also are recorded in other systems, and that are assigned portable identifiers that are used across multiple systems to track the entity. These identifiers are constant as a resource (or other forms of representation of the real world entity) are copied around and moved from place to place. Some identifiers are assigned by external (government) agencies. Identifiers includes things like Patient MRNs, Provider Numbers etc. Often, because of distributed record processing, entities have many identifiers to carry, and there's a whole business in arbitrating between them.
As documented here, the guidance when constructing FHIR URLs is that they are recommended to be case sensitive and that it is up to the implementers to define their behavior.
In that context, is there any specific requirement for resource names in URLs to be Pascal cased or is that also something that implementers can decide?
The resource names are expected to be the same as they're defined in the specification. E.g. "CodeSystem". While servers are allowed to accept "codesystem", "cOdEsYsTeM", "CODESYSTEM", etc. any system that requests those is non-compliant.
I'm thinking about using IsBadCodePtr to distinguish a predefined resource type from a custom resource type name.
Is it good practice (or even the best method?) to use the IsBadCodePtr API to find out if a given resource type belongs to one of the predefined resource type or is there a better alternative?
Please note that I'm talking about resource type names and not IDs.
It is not good practice. You should instead use the IS_INTRESOURCE macro, which tells you if a resource pointer was created with MAKEINTRESOURCE (which means it isn't a real pointer). Note that this doesn't definitely mean it is "predefined", because you can call MAKEINTRESOURCE on your own resource IDs.
The IsBad____Ptr functions should not be used in general. As the documentation says:
This function is obsolete and should not be used.
There is more information in this blog post by Microsoft's Raymond Chen: IsBadXxxPtr should really be called CrashProgramRandomly.
The apiary.io list resource attributes in point form. Is there a specific convention to show what data type these attributes are, or met data specifying formats?
At the moment there is not convention for discussing resource's attributes in the API Blueprint. What comes close is planned Message-body Attributes Description.
But I feel what would be the real solution is what the concept of a future API Blueprint – Resource Blueprint proposes under semantic data definition (of a resource). Refer to the example resource blueprint.
So while none of the previous is implemented, if you are looking for a convention, I would suggest consider the one as proposed in resource blueprint e.g.:
# Resource [/resource]
## Attributes
+ ip (string) ... ipv4 or ipv6 address associated with the resource
+ some-other-attribute (number, optional, `42`) ... a number of something