This is another report for one more failure year, but, I hope, for the last such one (as I’m doing very serious things to prevent this in future). In this year, I finally realized, that I got into a comfort zone (again), which did not allow me to move forward and which, eventually, appeared to be not really comfort. Now I understand, that this could be seen just by reading my previous reports (for 2015-2016), but I was too “blind” (that’s, actually, how the comfort zone works).
Anyway, this year became a breaking point and that’s, probably, an achievement.
Unfortunately, the failures are still there and they are almost the same as for the previous years:
I left Kayako one week less than two months ago. During this time I was trying to rest, to work on tools like CD-Index and to arrange my working environment (CD-Index is actually helping with this too).
During these (almost) two months I did not really look for a new job (yet). As there still too many things to complete at my home office (CD-Index and Orangutan are among them). Anyway, I plan to do this. I will be looking for a part-time remote job. I can do PHP, Ruby, C, Perl and many other things (check my profiles on LinkedIn and on Upwork). So, if you a looking for a developer like me, contact me (e.g., using the Hire button in the top right corner of this page). If you have some short-time project, like a Redmine plugin, I can do this too.
]]>This is the approach, which is propagated by such famous API designers as Apigee and which was also taken by Kayako, when we were designing our API. And, that’s why we decided to use the current approach for the partial output, which we implemented with the help of the special fields=
argument, that should be specified in the request URI.
It terms of Kayako API, field is a property of the API resource object.
The basic rules of using the fields=
argument are simple as:
1. Use +
to request the field to be always specified and…
2. Use -
to request the field to be skipped.
Examples:
?fields=+title
?fields=-resource_url
The latter rule, however, won’t work, if the field is mandatory. Mandatory fields, such as id
, are always included, whatever is in fields=
.
These basic rules are generally enough for using the fields=
argument. But, actually, this argument is much more flexible than that. We asked ourselves, what should the API framework do, if the user specifies field names without +
and -
? It’s obvious, that, if this is the case, the user means to include these fields into the response. But generally, this looks like an exclusive list of the fields, that should be included:
?fields=id,name,resource_type
The number of fields in the resource presentation can be huge (depending on resource) and not all of them can actually be needed by the user. Therefore, in Kayako API we used the concept of the default presentation, which includes not all of the resource’s fields. Fields, which are not included into this presentation, we call optional.
So, to include an optional field users can use +
. To exclude a field from the default presentation users can use -
. But, what if you want only a couple of certain fields to be there? We decided not to require you to specify all the other fields, that you want to skip, with -
. Instead, we suggested the alternative: just list fields, which you want to include, in the fields=
argument (without +
and -
). In other words, in this way, you can define your own custom presentation of the resource. So, here comes the third rule of using the fields=
argument:
3. Just list the fields, which you want to be specified in the response, without +
.
But, this rule has one exception: Saying, in response users got all the fields, that they need, except an optional one, e.g., tags
. If they are aware of the fields=
argument, they can just specify it as follows:
?fields=tags
I.e., users can forget to add +
. So, we decided, that we won’t require the +
sign for such cases: if the specified field is optional, we won’t hide all other fields, which are returned by default, that is, we will treat it as +tags
. This can be outlined as the fourth rule:
4. If the field is missing by default, you can specify it without +
.