We are during design of our REST-API and we are wondering in what form REST endpoint should return data?
We have an endpoint that returns so-called "identity" objects that have different attributes.
Each 'identities' has unique string eg. UUID#cf684c35-200e-4936-8b63-e6e51b6e3569.
We are wondering which format the developers are more used to?
Like this below:
{
"UUID#cf684c35-200e-4936-8b63-e6e51b6e3569": {
"validity_date": 1608591121,
"visibility": "private"
},
"RFID#cf684c35-200e-4936-8b63-e6e51b6e3570": {
"validity_date": 1608591123,
"visibility": "public".
}
}
or
{
"results": [
{
"identity": "UUID#cf684c35-200e-4936-8b63-e6e51b6e3569",
"validity_date": 1608591121,
"visibility": "private"
},
{
"identity": "RFID#cf684c35-200e-4936-8b63-e6e51b6e3570",
"validity_date": 0,
"visibility": "1608591123"
},
]
}
What is your opinion?
TL;DR I recommend to use a list of objects (your second approach).
Let's take your objects to a more obvious example of users with an id and a name:
{
1: {
"name": "Michal"
},
2: {
"name": "Thomas"
}
}
[
{
"id": 1,
"name": "Michal"
},
{
"id": 2,
"name": "Thomas"
}
]
Both approaches can be used, I don't see any difference from the API-level itself.
But let's consider how an application might provide or consume such data:
fetching a database table of users (e.g. whose birthday is next week)
showing a table of users (e.g. user name and birthday)
processing the monthly salary to employees
All three examples use a list of users, which is the second approach. Since many applications operate on a list of entities, that's a common sense for APIs.
I think that it [] is better than it { "results": [] }.
Said it, on my opinion the 2nd is better because of [on some languages] is easier to map it than to map the 1st.
Related
I created a JSON server and this is the data that I'm using. However, when I'm trying to query the examlist and relate it to the students (i'd like to receive the students based on their ID (the picture below shows the REST query - I'm using ?_expand=student )) it won't display them. The code shows correct as per JSON validators, but my goal is to have them working.
The way my data is organized (the examlist table) won't display the students, because apparently, it cannot read their IDs. This database will be used for HTTP requests, hence I need it fully working.
I'll upload another image so that you can visualize my code.
Momentarily instead of my studentIDs, it's showing some random 0,1 numbers and the student IDs are being pushed down along the arbitrary tree.
(Just the examlist "table")
It's M:M relationship (relational database) and how I want it structured is:
Table "students" that contains information about the students;
I have "table" exams that contains information about the exams;
And then I have another "table" examlist which contains information about the EXAM (ExamID) and the students enrolled in it (basically relates the two abovementioned tables)
When I try querying the students through the "examlist" table, it won't work. However, the other "table" -- exam, does work.
My assumption is the way I have organized the students in the examlist "table" is not good, however, given my very little experience I cannot seem to see where the issue is.
I hope I cleared it out for the most of you! Sorry for any inconvenience caused.
{
"students": [
{
"id": 3021,
"nume": "Ionut",
"prenume": "Grigorescu",
"an": 3,
"departament": "IE"
},
{
"id": 3061,
"nume": "Nadina",
"prenume": "Pop",
"an":3,
"departament": "MG"
},
{
"id": 3051,
"nume": "Ionut",
"prenume": "Casca",
"an": 3,
"departament": "IE"
}
],
"exams": [
{
"id": 1,
"subiect": "Web Semantic",
"profesor": {
"Nume": "Robert Buchman"
}
},
{
"id": 2,
"subiect": "Programare Web",
"profesor": {
"Nume": "Mario Cretu"
}
},
{
"id": 3,
"subiect": "Medii de Programare",
"profesor": {
"Nume": "Valentin Stinga"
}
}
],
"listaexamene": [
{
"examId":1,
"Data Examen":"02/06/2022 12:00",
"studentId":
[
{
"id":3021
},
{
"id":3051
}
]
},
{
"examId":2,
"Data Examen":"27/05/2022 10:00",
"studentId":
[
{
"id":3021
},
{
"id":3051
}
]
},
{
"examId":1,
"Data Examen":"04/06/2022 10:00",
"studentId":
[
{
"id":3021
},
{
"id":3051
},
{
"id":3061
}
]
}
]
}
I had to repost with more information after my first one got closed down
I think I finally got the answer. The problem lays in the JSON server. Apparently, it cannot obtain information from further down the arbitrary tree, only the first layer.
Thank you all for your input on the previous post!
Our system needs to return several KPIs grouped in different topics:
Census:
citizens (number of inhabitants)
citizens without any studies
...
Information desk
Phone response time
Mail response time
...
Tax
Online payments
Window payments
...
To my understanding, it would make sense to have an entity for each topic and each KPI being a KeyPerformanceIndicator attribute. eg: This could work similar to:
{
"description": "Census Information system",
"dataProvided": {
"entities": [
{
"idPattern": ".*"
}
],
"attrs":[ //THIS SEEMS AN INTERESTING APPROACH, BUT SADLY ALSO INVALID
{
"name": "citizens",
"type": "KeyPerformanceIndicator"
},
{
"name": "citizens_without_studies",
"type": "KeyPerformanceIndicator"
},
//...
]
},
"provider": {
"http": {
"url": "http://myhost/v2/census"
}
}
}
(TL;DR: "attrs" supports strings only, so can't return complex/data modeled types, like KPI)
Setting this happy idea aside, what it would be a good approach to solve this?
Must each KPI be an entity?
Is NGSI-LD what I'm looking for?
I think your case can be solved in NGIv2. Let my try to explain.
Must each KPI be an entity?
Yes. That's the usual way of modelling KPIs according to the KPIs datamodel. Each KPI is modeled as an entity of type KeyPerformanceIndicator.
Can KPIs be categorized?
Yes. You can use the category attribute to do that.
For instance, you can have an KPI "Online payments" of category "Tax Information" modeled this way:
{
"id": "OnlinePayments",
"type": "KeyPerformanceIndicator",
...
"category": ["taxInformation"],
...
}
Note that category is an array, so a given KPI could belong to more than one category (although in your use case it seems that each KPI belongs to exactly one category so you don't need this feature)
How can I get KPIs that belong to a given category?
You can use regular Orion Context Broker filtering features for that. For instance, to get all KPIs in category taxInformation you could use this key:
GET /v2/entitites?type=KeyPerformanceIndicator&q=category:taxInformation
or this expression in subscriptions:
{
"subject": {
"entities": [
{
"idPattern": ".*",
"type": "KeyPerformanceIndicator"
}
],
"condition": {
...
"expression": {
"q": "category:taxInformation"
}
}
},
...
}
If what you are trying to accomplish is to offer an NGSI interface for your KPI data, you can just create your own adaptor on top of your database that offers a REST interface compliant with NGSI-LD and such service can just return entities of type KeyPerformanceIndicator. Then, you can federate it to a Context Broker with a simple registration i.e. for entities of type KeyPerformanceIndicator. And that's all.
The usage of Linked Data would be recommendable as well, so I would go for NGSI-LD, as it has been officially endorsed by ETSI.
I'm creating a procedure in a transaction bundle and add practitioners as actors to the performers collection, having different functions. As far as the practitioners references are unique, all is fine. But when I'm trying to add a practitioners twice, with a different functions, an exception is thrown:
Can not process entity with ID[urn:uuid:7165d406-da59-4436-aa93-372ca882c4e5], this is not a valid FHIR ID
I found this message in HAPI FHIR unit tests, but in my case, the uuid seems to be fine. But maybe only one uuid is replaced with the id of the created practitioner.
I'm also not sure, whether this is the correct way for what I want to achieve.
I also tried to add the practioner only once and then add the second role to function.coding. But the resulting entry looks for me kinda strange:
performer": [
{
"function": {
"coding": [
{
"system": "http://somewhere/performer-role",
"code": "88888888"
},
{
"system": "http://somewhere/performer-role",
"code": "99999999",
"display": "Role-2"
}
],
"text": "Role-1"
},
"actor": {
"reference": "Practitioner/2925"
}
},
I'm fairly new to Fhir. Does anybody knows what's wrong here ?
And, what's the recommended practice, to have one performer/actor in to different roles ?
Thanks in advance
P.S. I'm using HAPI FHIR 4.0
Multiple coding repetitions would be used to convey translations - so you're saying that 888888888 and 99999999 are two different codes that represent the same role. If you want to indicate that the same Practitioner had two different roles, then you need to have two different performer repetitions. E.g.
perfomer: [
{
"function": {
"coding": [ {
"system": "http://somewhere/performer-role",
"code": "88888888"
}]},
"actor": {
"reference": "Practitioner/2925"
}
}, {
"function": {
"coding": [ {
"system": "http://somewhere/performer-role",
"code": "99999999"
}]},
"actor": {
"reference": "Practitioner/2925"
}
}
]
I am reverse engineering an app that sends queries to
SOMESERVERNAME.analysis.windows.net/public/reports/querydata via an HTTP POST of an JSON-structured query.
Some initial lines of a sample query are at the end of this message.
I can't find any documentation on this anywhere. I don't know if this is some secret API or what. I ultimately would like to just ignore the aggregations altogether and just dump the raw data, which seems to sit in some flat-file type container on the back-end, but without some API documentation I'm stuck with just re-running the super basic handful of queries I've been able to intercept.
Note: this app is an embedded analytics page created with PowerBI, but the only REST API I can find for PowerBI has nothing to do with querying, but just basic object management.
Thanks!
{
"version": "1.0.0",
"queries": [
{
"Query": {
"Commands": [
{
"SemanticQueryDataShapeCommand": {
"Query": {
"Version": 2,
"From": [
{
"Name": "s",
"Entity": "Sheet1"
}
],
"Select": [
{
"Aggregation": {
"Expression": {
"Column": {
"Expression": {
"SourceRef": {
"Source": "s"
}
},
"Property": "Total"
}
},
"Function": 0
},
"Name": "Sum(Sheet1.Total)"
}
],
"Where": [
{
"Condition": {
"In": {
"Expressions": [
{
"Column": {
"Expression": {
"SourceRef": {
"Source": "s"
}
},
"Property": "Year"
}
}
],
"Values": [
[
{
"Literal": {
"Value": "'2018'"
}
}
]
]
}
}
},
............
I have built a client that scrapes data off a specific Power BI report using the same API, but probably you'll be able to adapt it to your use case. Maybe we can even abstract the code into a more generalized Power BI client!
Having tinkered with the API for two days, I realised that there are many ways the data can be formatted:
"nested"/multidimensional data can be unflattened, flattened by 1 degree, etc.
a primary "table" of a result dataset (in data.PH) can reference others (in data.SH)
The basics are as follows:
A dataset is structured like a multidimensional table, with cells containing values.
In a set of cells, the first always has a field S that contains the schema of its and all subsequent cells.
The schema maps a field of each cell's object with a selection from your query, e.g. the G0 field with the queried column age.
My client seems to work only with a specific type of query (SemanticQueryDataShapeCommand), a specific nr of dimensions and a specific column marked as primary (via Binding.Primary). But maybe that helps! https://github.com/derhuerst/fetch-bvg-occupancy/blob/1ebb864b1ff7130f9d2f0ab031c6d78bcabdd633/lib/parse-dataset.js
The only documented way to use this API is through the ADOMD.NET or OleDb provider.
If you want to send a DAX/MDX query and retrieve data programmatically, there's a sample of how to front-end the service with a simple REST API here.
I have a REST service that returns a list of objects. Each object contains objectcode and objectname.
This is my first time building a REST service, so I'm not sure how to format the response.
Should it be:
{
"objects": {
"count": 2,
"object": [
{
"objectcode": "1",
"objectname": "foo"
},
{
"objectcode": "2",
"objectname": "bar"
},
...more objects
]
}
}
OR
[
{
"objectcode": "1",
"objectname": "foo"
},
{
"objectcode": "2",
"objectname": "bar"
},
...more objects
]
I realize this might be a little subjective, but which would be easier to consume? I would also need to support XML formatted response later.
They are the same to consume, as a library handles both just fine. The first one has an advantage over the second though: You will be able to expand the response to include other information additional to the objects (for example, categories) without breaking existing code.
Something like
{
"objects": {
"count": 2,
"object": [
{
"objectcode": "1",
"objectname": "foo"
},
{
"objectcode": "2",
"objectname": "bar"
},
...more objects
]
}
"categories": {
"count": 2,
"category" : [
{ "name": "some category"}
]
}
}
Additionally, the json shouldn't be formatted in any way, so remove whitespace, linebreaks etc. Also, the count isn't really necessary, as it will be saved while parsing the objects themselves.
I often see the first one. Sometimes it's easier to manipulate data to have meta-data. For exemple google API use first one : http://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&sensor=true
It's not only the question of personal preference; it's also the question fo your requirements. For example, if I was in the same situation and I did need object count on client side then I'd go with first approach otherwise I will choose the second one.
Also please note that "classic" REST server mostly will work a bit different way. If some REST function is to return a list of objects then it should return only a list of URLs to those objects. The URLs should be pointing to details endpoints - so by querying each endpoint you may get details on specific single object.
As a client I would prefer the second format. If the first format only includes the number of "objects", this is redundant information.