Is there a rule to define a sequential list of links using HATEOAS?
It is easy to add self, next and previous links to a HATEOAS-based response. Below is a sample response:
{
links : [{
rel : "next",
href : "http://localhost:8080/persons?page=1&size=20"
}],
content : [{
id: "",
name: "",
lastname: "",
age: 0
}],
pageMetadata : {
size : 20,
totalElements : 30,
totalPages : 2,
number : 0
}
};
So, pagination with next and previous links is not difficult but I couldn't figure out how it is possible to access for example 10th page directly, for example using a select element (let's assume there are more than 10 pages). Should I add all the links to the response as, for example, page1, page2, page3, etc? Of course I know the format of the request so I could just create the appropriate query but that seems kind of wrong because the whole point seems to be not relying on the actual link of the service. I am not an expert on this issue and I couldn't find an answer in this site or from Google.
Thanks in advance.
The common solution is to use URI templates. Specifically, section 3.2.8 regarding Form-Style Query Expansion.
Assuming both page and size are optional, you would construct your link URI template as localhost:8080/persons{?page,size}.
URI templates do not define which values are acceptable; there's no mechanism for restricting page or size to numeric values. As such, you should include this template in addition to your existing next/prev links. I'm not exactly sure which link relation best describes such a resource, but "collection" doesn't seem too far off.
In order to use URI templates, you'll need a library in whichever languages will be producing/consuming the template. A quick search produced a list of libraries in various languages which you may find helpful.
Lastly, depending on your hypermedia format you may need to specify a templated URI as such. For example, HAL+JSON uses a boolean templated property.
{
"_links": {
"collection": {
"href": "/persons{?page,size}",
"templated": true
}
}
}
Related
I'm an absolute FHIR newbie and I'm trying to create a set of StructureDefinitions and examples for an upcoming medical project.
For this project, we need a very specific resource, which is not supported by any FHIR resource yet. Here's our use case:
We are placing sensors on our Patients while they execute certain exercises (e.g. a leg squat) - we capture the sensor measurements and based on those we assign a pre-calculated bio-mechanical body model to each individual Patient. Those body models are calculated and assigned somewhere else in our system (this process is not relevant here). In a first step, I would like to add all the pre-calculated body models itself to our FHIR dataset as resources - so that I'm able to output all existing body models in our system.
Such a body model consists of an unique identifier, a human readable title and a set of attributes which describe the body model. The crucial part are the attributes - those might vary for each body model and we don't know the set of possible attributes beforehand, hence I need a dynamic format representing key and value of each attribute. If I were to represent this in a simple json structure I'd look as follows:
{
"id": "0",
"title": "SAMPLE_BODY_MODEL",
"attributes": [
{
"key": "ATTRIBUTE_1",
"value": "EXAMPLE_1"
},
{
"key": "ATTRIBUTE_2",
"value": "EXAMPLE_2"
}
]
}
My goal now is to create a StructureDefinition corresponding to the custom resource I've described above.
Hence I looked up the topic of "custom resources" and found this article on the HL7 site: https://hl7.org/fhir/basic.html - explaining that the Basic resource should be used for custom resources.
So I went ahead and tried to create a basic resource and extending it:
{
"resourceType": "StructureDefinition",
...
"type": "Basic",
"differential": {
"element": [
{
"id" : "Basic",
"path": "Basic",
"definition": "This element describes a general body model captured during an exercise or a movement, e.g. whilst doing leg squats."
},
{
"id" : "Basic.id",
"path": "Basic.id",
"definition": "ID of the body model"
}
{
"id": "Basic.extension:title",
"path": "Basic.extension",
"sliceName": "definition",
"definition": "Title of the body model",
"min": 0,
"max": "1",
"type": [
{
"code": "string" // I know that's wrong, but I somehow would like to restrict this to a string only
}
]
},
{
"id": "Basic.extension:attributes",
"path": "Basic.extension",
"sliceName": "attributes",
"definition": "Attributes of the body model",
// This is where I'm stuck - how do I define this to be a list of objects consisting of attributes key and value?
}
]
}
}
To sum it all up: How do I create a new StructureDefinition from a basic resource allowing me to specify a new required attribute named "attributes", which consists of one-to-many elements, which again contain the attributes key and value for the key and value of the body model attributes?
Hope this makes sense - otherwise please feel free to let me know and I'll try to rephrase my question.
Many thanks in advance!
First, for a newbie, you're doing really well :) (And nice job on framing the question well too!)
Your first extension slice has a few issues:
sliceName should be "title", not "definition" - essentially the 'extra' bit in the id is the slicename
The 'type' needs to be Extension. (The type of all extensions is always Extension.) However, you should also specify a specific profile on Extension that indicates the canonical URL the StructureDefinition you've used to define the 'title' extension. That extension will have a context of Basic and will constrain extension.value[x] to be of type string and will also establish a fixed URL for extension.url.
Your second slice will be similar. However, the profile on extension it points to won't constrain extension.value. Instead, it'll slice extension.extension to have two slices, one with a fixed url of "name" and the other with a fixed url of "value". There's an example here of a 2-element complex extension. Your slice names and data types will differ, as will the context, but it should make a good model for you.
If you still have issues, add your revised version to your question and we'll see if we can help further.
I have registered this extension under an Imaging Study Resource and added a Custom Search Parameter for it.
"extension": [{
"url": "http://example.org/fhir/StructureDefinition/middlename-extension",
"extension": [{
"url": "middlename",
"valueString": "Rocky"
}
]
}
]
I want to now search for the valueString "Rocky" across the server and return any Imaging Study which has this extension value.
How can I define the Description and Xpath while registering the search parameter for this usecase?
I tried this but this would not work, am i missing something?
"expression" : "ImagingStudy.extension.where(url='http://example.org/fhir/StructureDefinition/middlename-extension').extension(url='middlename').value.as(String)",
"xpath" : "f:ImagingStudy/f:extension/f:extension/f:value/f:as[#valueString]"
The expression should either be
"ImagingStudy.extension.where(url='http://example.org/fhir/StructureDefinition/middlename-extension').extension.where(url='middlename').value.as(String)"
or
"ImagingStudy.extension('http://example.org/fhir/StructureDefinition/middlename-extension').extension('middlename').value.as(String)"
The xPath isn't used by any servers that I'm aware of, but for the record, it should be:
"f:ImagingStudy/f:extension[#url='http://example.org/fhir/StructureDefinition/middlename-extension']/f:extension[#url='middlename']/f:valueString/#value"
As a side note, you shouldn't be using a custom extension for the middle name. Middle names are conveyed as any repetition of HumanName.given other than the first. If you want to send a middle name without a first name, you could put a dataAbsentReason extension on the first 'given' repetition.
I'm writing a controller that handles an array of object, something like:
#PostMapping("/post")
public void saveEmployeeArray(#RequestBody Emoloyee[] employeeArray)
{
// Method body
}
Keep in mind that, in this case, employees are usually created, update, or deleted in bulk, meaning, I usually need to handle multiple employees at the same time.
A colleague told me that although it works I should only handle one employee in the controller as, according to him, it's rest best practice. But he didn't present an alternative to the issue of having to handle multiple employees most of the time, other than making multiple requests.
My question is, how is the best way to handle multiple objects?
If your list of Employee is inside another data structure (e.g. company), you can offer PATCH operation for outer resource to add or change a list of Employees. JSON PATCH is specified in RFC 6902, see https://datatracker.ietf.org/doc/html/rfc6902/
The JSON body of a PATCH request would look like this:
[
{ "op": "add", "path": "/employees", "value": { "name": "Employee 1", ...} },
{ "op": "add", "path": "/employees", "value": { "name": "Employee 2", ...} },
...
]
The body is a list of PATCH operations to change the addressed data structure at several places within one request, so it fits to your requirement.
The specification in RFC 6902 offers more than just adding elements, you can also remove, replace, move, copy and test. Have a look in the RFC for good and simple examples.
I'm trying to implement a HATEOAS Rest Client using Spring Boot.
Right now, I'm stuck in a point where I need to convert HATEOAS into an actual API URI.
If I post a new object of type Customer like:
{
"name": "Frank",
"address": "http://localhost:8080/address/23"
}
And then I retrieved with a request to http://localhost:8080/api/customer/1`, HATEOAS gives me something like
{
"name": Frank,
"_links": {
"address": {
"href": "http://localhost:8080/api/customer/1/address"
}
}
}
Is it possible to convert a link of the form of http://localhost:8080/api/customer/1/address to an API call like http://localhost:8080/api/address/23 ?
If you see what HATEOS returns after you say,
GET: http://localhost:8080/api/customer/1
is
{
"name": Frank,
"_links": {
"address": {
"href": "http://localhost:8080/api/customer/1/address"
}
}
}
According to Understanding HATEOS,
It's possible to build more complex relationships. With HATEOAS, the output makes it
easy to glean how to interact with the service without looking up a specification or
other external document
which means,
after you have received resource details with
http://localhost:8080/api/customer/1
what other operations are possible with the received resource those will be shown for easier/click thru access to your service/application,
here in this case HATEOS could find a link http://localhost:8080/api/customer/1/address that was accessible once you have customer/1 and from there if you want then without going anywhere else customer/1 's address could be found with /customer/1/address.
Similarly if you have /customer/1's occupation details then there would be another link below address link called http://localhost:8080/api/customer/1/occupation.
So if address is dependent on customer i.e. there can be no address without customer then your API endpoint has to be /api/customer/1/address and not directly /api/address/23.
However, after understanding these standards and logic behind HATEOS's such responses if you still want to go with your own links that may not align with HATEOS's logic you can use,
Link Object provided by LinkBuilder interface of HATEOS.
Example:
With object of type Customer like:
Customer c = new Customer( /*parameters*/ );
Link link= linkTo(AnyController.class).slash("address").slash(addressId);
customer.add(link);
//considering you want to add link `http://localhost:8080/api/address/23` and `23 is your addressID`.
Also you can create a list of Links and keep adding many such links to that list and then add that list to your object.
Hope this helps you !
Question. How do I avoid n+1 queries with Spring Data REST?
Background. When querying Spring Data REST for a list of resources, each of the resulting top-level resources has links to the associated resources, as opposed to having the associated resources embedded directly in the top-level resources. For example, if I query for a list of data centers, the associated regions appear as links, like this:
{
"links" : [ {
"rel" : "self",
"href" : "http://localhost:2112/api/datacenters/1"
}, {
"rel" : "datacenters.DataCenter.region",
"href" : "http://localhost:2112/api/datacenters/1/region"
} ],
"name" : "US East 1a",
"key" : "amazon-us-east-1a"
}
It is pretty typical, however, to want to get the associated information without having to do n+1 queries. To stick with the example above, I might want to display a list of data centers and their associated regions in a UI.
What I've tried. I created a custom query on my RegionRepository to get all the regions for a given set of data center keys:
#RestResource(path = "find-by-data-center-key-in")
Page<Region> findByDataCentersKeyIn(
#Param("key") Collection<String> keys,
Pageable pageable);
Unfortunately the links this query generates don't overlap with the links that the data center query above generates. Here are the links I get for the custom query:
http://localhost:2112/api/regions/search/find-by-data-center-key-in?key=amazon-us-east-1a&key=amazon-us-east-1b
{
"links" : [ ],
"content" : [ {
"links" : [ {
"rel" : "self",
"href" : "http://localhost:2112/api/regions/1"
}, {
"rel" : "regions.Region.datacenters",
"href" : "http://localhost:2112/api/regions/1/datacenters"
}, {
"rel" : "regions.Region.infrastructureprovider",
"href" : "http://localhost:2112/api/regions/1/infrastructureprovider"
} ],
"name" : "US East (N. Virginia)",
"key" : "amazon-us-east-1"
}, {
"links" : [ {
"rel" : "self",
"href" : "http://localhost:2112/api/regions/1"
}, {
"rel" : "regions.Region.datacenters",
"href" : "http://localhost:2112/api/regions/1/datacenters"
}, {
"rel" : "regions.Region.infrastructureprovider",
"href" : "http://localhost:2112/api/regions/1/infrastructureprovider"
} ],
"name" : "US East (N. Virginia)",
"key" : "amazon-us-east-1"
} ],
"page" : {
"size" : 20,
"totalElements" : 2,
"totalPages" : 1,
"number" : 1
}
}
The challenge seems to be that the data center query returns links that aren't particularly informative once you already understand the shape of the data. For example, I already know that the region for data center 1 is at /datacenters/1/region, so if I want actual information about which specific region is involved, I have to follow the link to get it. In particular I have to follow the link to get the canonical URI that shows up in the bulk queries that would allow me to avoid n+1 queries.
The reason Spring Data REST works like this is the following: by default, we assume every application repository a primary resource of the REST service. Thus, if you expose a repository for an entity's related object you get links rendered to it and we expose the assignment of one entity to another via a nested resource (e.g. foo/{id}/bar).
To prevent this, annotate the related repository interface with #RestResource(exported = false) which prevents the entities managed by this repository from becoming top level resources.
The more general approach to this is starting with Spring Data REST letting you expose the resources you want to get managed and default rules applied. You can then customize the rendering and links by implementing ResourceProcessor<T> and registering your implementation as Spring bean. The ResourceProcessor will then allow you to customize the data rendered, links added to the representation etc.
For everything else, manually implement controllers (potentially blending into the URI space of the default controllers) and add links to those through ResourceProcessor implementations. An example for this can be seen in the Spring RESTBucks sample. The sample project uses Spring Data REST to manage Order instances and implements a custom controller to implement the more complex payment process. Beyond that it adds a link to the Order resource to point to the manually implemented code.
Spring Data REST will only create the representation you describe if the serializer that is configured inside the Jackson ObjectMapper is triggered by seeing a PersistentEntityResource, which is a special kind of Resource that is used inside Spring Data REST.
If you create a ResourceProcessor<Resource<MyPojo>> and return a new Resource<MyPojo>(origResource.getContent(), origResource.getLinks()), then the default Spring Data REST serialization machinery will not be triggered and Jackson's normal serialization rules will apply.
Note, however, that the reason Spring Data REST does associations the way it does is because it's very difficult to arbitrarily stop traversing an object graph when serializing to JSON. By handling associations the way it does, it guarantees that the serializer won't start traversing an object graph that is N levels deep and become much slower in performance and in the performance of the representation going over-the-wire.
Ensuring that Jackson does not try to serialize a PersistentEntityResource, which is what it's doing in the default configuration, will ensure that none of the Spring Data REST handling of associations is triggered. The down side to this, of course, is that none of Spring Data REST's helpers will be triggered. If you still want links to the associated resources, you'll have to make sure you create those yourself and add them to the outgoing plain Resource.