Blog

There are two ways, in which you can design your API – you can create it for applications or you can create it for users. Historically, APIs were created for applications, what, I believe, was wrong. Your API is another your service, so it should be as friendly to the end user as possible, just like your normal services. And, it’s the user (e.g., a developer), that uses your API, not an application, that he/she is possibly writing (thus, some users can use your API through command-line CURL).

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 +.