I want to send JSON structured something like this
{
"buttons": {
"track": {
"type": 0,
"visibility": 1,
"visibility_text": "I am visible"
},
"call": {
"type": 0,
"visibility": 1,
"visibility_text": "I am visible"
}
// 12 or so more children of button node
}
}
As you can see, there is a lot of duplication going on here. I am thinking of sending sending a token separated string rather repeating the type, visibility and visibility_text nodes. Something like this
{
"buttons": {
"track": "0|1|I am visible",
"call": "0|1|I am visible"
}
}
The amount of data to be transferred is greatly reduced, but at the cost of readability, which is not a high concern since this is a private API.
What are the pros and cons of the second approach? Any other suggestions are welcome too.
What are the pros and cons of the second approach?
Cons
unreadable
order of parameters is crucial
requires manual parsing
cannot use the delimiter | in string literals
Pros
None. It's 2016, a couple of extra lines in a payload doesn't increase the performance.
Go for readability. The api is private now, but in the future it may not be. Or it may have to be maintained by someone other than you.
Go for ease of parsing. Having to implement custom json parsing introduces code that was not necessary. Having to take into account in which order the parameters are is not something you want to do. If they are accidentally are mixed up, everything breaks.
Related
Currently, I have an API end point that needs to return a list of items in a JSON format. However, each of the items that are returned has a different structure.
E.g. Think of a feed API. However, the structure of each item within the API can be very different.
Is it standard to return API response with multiple items - each with a different structure?
A made-up sample below to show different structures.
Store, Candy, and Personnel in the example is logically the same thing in my case (3 different items). Howevever, the structuring underneath can be very different - with different key-value pairs, different levels of nesting, etc.
{
"store":{
"book":[
{
"category":"reference",
"author":"Nigel Rees",
"title":"Sayings of the Century",
"price":8.95
},
{
"category":"fiction",
"author":"Evelyn Waugh",
"title":"Sword of Honour",
"price":12.99
}
],
"bicycle":{
"color":"red",
"price":19.95
}
},
{
"candy":
{
"type":"chocolate",
"manufacturer":"Hershey's",
"cost":10.00,
"reduced_cost": 9.00
},
},
{
"Personnel":
{
"name":"chocolate",
profile:
{
"Key": "Value",
"Key": "Value",
something:
{
"Key": "Value",
"Key": "Value",
}
}
},
},
}
There are no strict rules to REST in terms of how you design your payloads. However, there are still certainly things to consider obviously when doing so. Without knowing really the specifics of your needs it's hard to give specific advice but in general when it comes to designing a JSON REST API here is what I think about.
On average, how large will my payload be. We don't want to pass large amounts of data on each request. This will make your application extremely slow and perhaps even unusable on mobile devices. For me, the limit in the absolute worse case is 1mb and maybe this is even too high. If you find your payload is too large, break it down into separate resources. For example rather than including the books in the response to your stores resource, just reference the unique id's of the books that can be accessed through /stores/books/{id}
Is it simple enough that a person who stumbles across the resource can understand the general use of it. The simpler an API is the more useful it is for users. If the structure is really complex, perhaps breaking it into several resources is a better option
This point sort of balances number #1. Try and reduce the number of requests to get a certain piece of data as much of possible (still considering the other two points above). Excessively breaking down payloads into separate resources also reduces performance.
Unfortunately Googling this results in "dictionary" being interpreted as a data structure, instead of as a language dictionary.
I'm looking for something along the lines of:
[
{
"english": "hello",
"german": "hallo",
"definitions": {
"english": "A word of greeting"
}
}
]
I realise anyone can make something up but if there's a standard spec available that would be helpful.
If there were a standard, it would be developed by professional lexicographers who know that a dictionary is an awful lot more than a simple list of synonyms; it would be a vastly more complex standard than you are probably looking for.
Also, you'll probably find there is more than one standard (or proposed standard) and you have to choose between them.
A quick google came up with:
DML: https://hal.archives-ouvertes.fr/hal-00968835/document
XDXF: https://en.wikipedia.org/wiki/XDXF
GenoPro: https://www.genopro.com/sdk/Report-Generator/Dictionary/
An IBM format: https://www.ibm.com/support/knowledgecenter/en/SS8NLW_11.0.2/com.ibm.discovery.es.ta.doc/iiystlexxml.html
TEI: http://people.ds.cam.ac.uk/blf10/Links/TEI.html
dicML: probably dead.
My app has two kind of objects, one is the location and the one is the route that goes from locationA to locationB.
location looks like this:
{
"idLocationX" : {
"address" : string
}
}
route looks like this:
{
"idLocationA": {
"idLocationB": {
"time": number,
"distance": number
}
}
}
I decided on that structure for route because initially I thought, I could just go ahead and access /routes/idLocationA/idLocationB but that was obvious shortsighted.
I know that Firebase advices against nesting objects but I feel it's still the right and best way to quickly access the route while still keeping the overall data structure as lean as possible.
The alternative would now be to change the route structure to something like this:
{
"idLocationA": true,
"idLocationB": true,
"start": "idLocationA",
"end": "idLocationB",
"time": number,
"distance": number
}
That structure is obviously a lot leaner but I would need to do a different query and it feels less natural.
Can someone explain to me if there is a way to get data structure 1 for route (the current one, firstly mentioned above) to work in a Firebase database setting? I would basically need to get the path /routes/{placeholder}/idLocationA/idLocationB working.
A coworker and I are in a heated debate regarding the design of a REST service. For most of our API, GET calls to collections return something like this:
GET /resource
[
{ "id": 1, ... },
{ "id": 2, ... },
{ "id": 3, ... },
...
]
We now must implement a call to a collection of properties whose identifying attribute is "name" (not "id" as in the example above). Furthermore, there is a finite set of properties and the order in which they are sent will never matter. The spec I came up with looks like this:
GET /properties
[
{ "name": "{PROPERTY_NAME}", "value": "{PROPERTY_VALUE}", "description": "{PROPERTY_DESCRIPTION}" },
{ "name": "{PROPERTY_NAME}", "value": "{PROPERTY_VALUE}", "description": "{PROPERTY_DESCRIPTION}" },
{ "name": "{PROPERTY_NAME}", "value": "{PROPERTY_VALUE}", "description": "{PROPERTY_DESCRIPTION}" },
...
]
My coworker thinks it should be a map:
GET /properties
{
"{PROPERTY_NAME}": { "value": "{PROPERTY_VALUE}", "description": "{PROPERTY_DESCRIPTION}" },
"{PROPERTY_NAME}": { "value": "{PROPERTY_VALUE}", "description": "{PROPERTY_DESCRIPTION}" },
"{PROPERTY_NAME}": { "value": "{PROPERTY_VALUE}", "description": "{PROPERTY_DESCRIPTION}" },
...
}
I cite consistency with the rest of the API as the reason to format the response collection my way, while he cites that this particular collection is finite and the order does not matter. My question is, which design best adheres to RESTful design and why?
IIRC how you return the properties of a resource does not matter in a RESTful approach.
http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
From an API client point of view I would prefer your solution, considering it is explicitly stating that the name of a property is XYZ.
Whereas your coworkers solution would imply it is the name, but how would I know for sure (without reading the API documenation). Try not to assume anything regarding your consuming clients, just because you know what it means (and probably is easy enough to assume to what it means) it might not be so obvious for your clients.
And on top of that, it could break consuming clients if you are ever to decide to revert that value from being a name back to ID. Which in this case you have done already in the past. Now all the clients need to change their code, whereas they would not have to in your solution, unless they need the newly added id (or some other property).
To me the approach would depend on how you need to use the data. Are the property names known before hand by the consuming system, such that having a map lookup could be used to directly access the record you want without needing to iterate over each item? Would there be a method such as...
GET /properties/{PROPERTY_NAME}
If you need to look up properties by name and that sort of method is NOT available, then I would agree with the map approach, otherwise, I would go with the array approach to provide consistent results when querying the resource for a full collection.
I think returning a map is fine as long as the result is not paginated or sorted server side.
If you need the result to be paginated and sorted on the server side, going for the list approach is a much safer bet, as not all clients might preserve the order of a map.
In fact in JavaScript there is no built in guarantee that maps will stay sorted (see also https://stackoverflow.com/a/5467142/817385).
The client would need to implement some logic to restore the sort order, which can become especially painful when server and client are using different collations for sorting.
Example
// server sent response sorted with german collation
var map = {
'รค':{'first':'first'},
'z':{'second':'second'}
}
// but we sort the keys with the default unicode collation algorigthm
Object.keys(map).sort().forEach(function(key){console.log(map[key])})
// Object {second: "second"}
// Object {first: "first"}
A bit late to the party, but for whoever stumbles upon this with similar struggles...
I would definitely agree that consistency is very important and would generally say that an array is the most appropriate way to represent a list. Also APIs should be designed to be useful in general, preferably without optimizing for a specific use-case. Sure, it could make implementing the use-case you're facing today a bit easier but it will probably make you want to hit yourself when you're implementing a different one tomorrow. All that being said, of course for quite some applications the map-formed response would just be easier (and possibly faster) to work with.
Consider:
GET /properties
[
{ "name": "{PROPERTY_NAME}", "value": "{PROPERTY_VALUE}", "description": "{PROPERTY_DESCRIPTION}" },
...
]
and
GET /properties/*
{
"{PROPERTY_NAME}": { "value": "{PROPERTY_VALUE}", "description": "{PROPERTY_DESCRIPTION}" },
...
}
So / gives you a list whereas /* gives you a map. You might read the * in /* as a wildcard for the identifier, so you're actually requesting the entities rather than the collection. The keys in the response map are simply the expansions of that wildcard.
This way you can maintain consistency across your API while the client can still enjoy the map-format response when preferred. Also you could probably implement both options with very little extra code on your server side.
Which is the better data format for a JSON. The requirement is to be able to store and retrieve information about how many projects are deployed on to a server.
Object-Based Design
{
"Server1":{
"project1":{
"buildNo":"290",
"deployed":"12/12/2012"
},
"project2":{
"buildNo":"291",
"deployed":"11/12/2012"
},
"project3":{
"buildNo":"209",
"deployed":"11/12/2012"
}
}
}
Array-Based Design
{
"Server1":[
{"project1":{
"buildNo":"290",
"deployed":"12/12/2012"
}},
{"project2":{
"buildNo":"291",
"deployed":"11/12/2012"
}},
{"project3":{
"buildNo":"209",
"deployed":"11/12/2012"
}}
]
}
Please do let me know your thoughts for or against either of these approaches.
Is the order of projects significant?
If it is, then an array is the simplest way to represent that.
If it is not, then array requires an unnecessary preprocessing step to map array indexes to project names before you can access them by name.
My thoughts:
Parsing:
Both are of similar complexity.
Adding/Deleting:
Both are of similar complexity
Readability/Representation of Information:
The first indicates a fixed structure whereas the second suggests that projects may be added removed later.