The FHIR specification has a number of resources:
http://hl7.org/fhir/2018May/resourcelist.html
Suppose a doctor:
recommended bedrest for a patient or:
recommended daily exercise
how would these things be recorded in FHIR (which resource type)?
I don't see 'PatientOrder', 'PatientRecommendation', 'PatientIntervention', etc...
Your choices are CarePlan or ServiceRequest.
Note FHIR versioning: You should look at either http://hl7.org/fhir (for the current official release - STU3) or http://build.fhir.org (for the draft of the next release - R4). The 2018May was a frozen snapshot for ballot but won't be supported by any implementations.
Related
One of the benefits being promoted for API-first design or OpenAPI is that of their use as a single source of truth. To my mind, these schemas only serve as a contract - the actual source of truth for your API lies in your microservices implementation (typically a http endpoint).
How can OpenAPI claim to be a single source of truth when the contract cannot be enforced until the implementation on the API side is complete? I realise there is tooling available to assist with this, such as validation middleware that can be used to match your request and response against your schema, however this is typically only validated at the point that a network request is made, not at compile time.
Of course you could write api tests to validate, but this is very much dependent on good test coverage and not something you get out of the box.
TLDR - OpenAPI markets itself as being a single source of truth for APIs, but this simply isn't true until your API implementation matches the spec. What tools/techniques (if any) can be used to mitigate this?
Did a bit of additional research into available tooling and found a solution that helps mitigate this issue:
open-api-backend (and presumably other such libraries) have capabilities to map your api routes/handlers to a specific openAPI operation or operationID. You can then enforce schema validation such that only routes defined in the spec can be implemented, else a fail-fast error is thrown)
I'm developing a REST API around an ecommerce site and one of my resources is an Order which contains information like went it was made, the ID, the status, when it will be shipped, etc.
I have defined a media type for my Order resource like so:
application/vnd.myapp.order.v1+json
I also have defined another resource which is the status of an order, like so:
application/vnd.myapp.order-status.v1+json
My question is around the versioning of these media types. Seeing as they're related, would it make sense to version them in lockstep? For example, if the representation of the order resource changes and I create a application/vnd.myapp.order.v2+json, would it wise to also bump the version of the order-status media type to v2 as well? I'm also wondering if any there is a RESTful option with regards to the guidelines. I did have a look around online and couldn't really find anything talking about the best practice here, so any advice/opinions are appreciated.
I don't think mixing version and media type is a good idea.
In my opinion, you should separate it according to 'separate concerns principle' and 'single responsibility'.
https://en.wikipedia.org/wiki/Separation_of_concerns
https://en.wikipedia.org/wiki/Single-responsibility_principle
Many teams use header/url for versioning:
For example:
/api/v1/
/api/v2/
header {version:'v1'}
header {version:'v2'}
Then we can easily map the request with our need:
#RequestMapping(value="api/v1/books", consumes="application/json")
#RequestMapping(value="api/v2/books", consumes="application/json")
or
#RequestMapping(value="api/books",headers="version=v1", consumes="application/json")
#RequestMapping(value="api/books",headers="version=v2", consumes="application/json")
Although it seems useful it would be a violation of SoC and cause additional issues down the line as your API evolves.
Versioning your URLs is the better choice here, as URL is a perfect way to signal what type of resource is being dealt with and relation to the data it handles.
(To me introducing a custom header sounds much better design-wise then a custom versioned media type)
Custom media types are generally supposed to tell a consumer about the type of the data and its encoding scheme (e.g. xml vs json vs plain text and so on) and not how your fields are arranged from version to version while the encoding scheme is literally unchanged.
By choosing this path you would:
Force consumers of your API to tightly couple to that specific “representation” that creates maintenance issues on both sides.
Whenever you have multiple “versions” of your API co-existing at a given time - it introduce ambiguity when bodiless https methods such as DELETE or HEAD are used as the request information would simply be insufficient to correctly route your request, let alone the backend code completely.
It renders rels (Link Relation Types) less usable in their normal form (if you’d ever want to introduce them)
I'm trying to extend and override the FHIR schema and run it on the local server.
Could you please suggest me is there any way to customize the FHIR schema and run in local
Obviously if you want to just download the FHIR schemas, you're free to edit them to your heart's content and, but if your instances aren't valid against the un-edited schemas, then your systems will not be FHIR-conformant and you won't interoperate with systems or tools that depend on FHIR conformance (which is most of them).
Also, be aware that the schemas only reflect a small portion of the rules for conformance. XML schemas don't check slicing, vocabulary bindings, invariants or logs of other rules that must also be met. Most systems using FHIR don't use schema validation at all, or use it only as an initial "quick check" and will still conduct more thorough code-based validation against he rules in the FHIR spec.
There should never be a situation where you need to modify the FHIR schemas. The expectation in FHIR is that the 'extension' element will be used to convey additional data elements if any are required. If you need to represent a concept that FHIR doesn't have a resource for at all, then you can use 'basic'. In some cases (if the element doesn't have a required vocabulary binding) you may be able to send an extension such as 'data-absent-reason' in place of sending an actual value. The only situation where there's no mechanism to avoid populating an element and sending it as FHIR requires is if there's a mandatory coded element with a required binding. Those are both rare and generally easy to satisfy, though you may need to map your internal codes to FHIR to populate the element.
Rather than trying to modify the schema, you might be better served by asking the community (e.g. http://chat.fhir.org) how to meet your needs within the FHIR specification as it stands.
Say I have an API that (along with other entities) deals with tasks. My endpoints would look something like
GET /api/tasks //List all tasks
POST /api/tasks //Create a new task
GET /api/task/1 //Fetch a single task
PUT /api/task/1 //Update a single Tasks
GET /api/task/1/comments //Get the comments of task 1
I also need a few subsets of Task data which has an entirely different formats:
user-tasks, tasks for a user but shaped according to schedule.
sync-data, all tasks that need to be sent to an external system with special references
I can see the user data could exist off the user hierarchy such as
GET /api/user/1/tasks //tasks for this user with dedicated
But what of sync-data? Should this fall under the tasks heirarchy or under the system it's intended for such as
GET /api/ExternalSystemA/tasks //tasks for synchronization
REST doesn't care what spelling conventions you use for your URI. Any spellings that are consistent with the production rules in RFC 3986 are fine.
Relative resolution provides a standardized mechanism for computing a new URI from a context and a relative reference. Designing your hierarchy so that you can take advantage of that is, in some cases, a really good idea.
Otherwise, it is a lot like choosing a variable name - the machine doesn't care, so you just want to choose spellings that are satisfactory for other human beings; in other words, making sure that you are consistent with local conventions.
I maintain VaporShell, a PowerShell module to abstract CloudFormation template creation. As part of the CI pipeline, it pulls down the current CloudFormation specification JSON to generate the functions for resource types and resource property types.
Is there a similar specification JSON (or YAML) for SAM?
I currently manually maintain the SAM specific code, but I'd like to ensure that any new resources / properties / etc are pulled in as the SAM team releases them. If I have a JSON or YAML specification available, that would make my life much easier as well as ensure up-to-date SAM support within VaporShell.
Thank you!
Unfortunately for the AWS::Serverless types, there is no officially maintained specification:
https://github.com/awslabs/serverless-application-model/issues/1133
but there seems to be an unofficial specification many projects share so the maintenance can be shared across projects at least:
https://github.com/awslabs/goformation/blob/master/generate/sam-2016-10-31.json