For some of the endpoints (tags, tag aliases) in the API documentation it has the following message: "If your query succeeds but produces no results, you will receive instead the following special value"

When I hit the endpoints to get tags or tag aliases, I predictably get a JSON array containing the elements of the requested page, but as soon as I request a page that has no elements, I get the "special value", which is NOT a JSON array, yet still returns with status 200. We go from getting [{...},{...},...] to { "tags":[] }.

Aside from complicating implementations of clients for this API, what is the rationale for this behavior? Is there something wrong with the obvious expected behavior of simply returning an empty array?

I can't speak for other developers, but from my perspective I expect not to see the structure of the JSON to change so dramatically between valid requests to the same endpoint that return successfully with status 200. If it is truly such a "special" case, I would argue that it should return a response with status 400 and an error message about the page being out of bounds. That said, I don't think this is a special case and I think it should just return [] with status 200.

I assure you that this isn't an intentional behavior. It's a quirk of how Rails handles empty collections for automatic serialization. It will refuse to serialize an empty collection unless you specify what data types it can contain, or if you specify a root key. The root key is the easier way and prevents a host of other data type problems so it was used by most of the endpoints, and it's automatically defined by some of the frameworks used. So empty collections end up using a different format and I don't have an easy way to fix it without rewriting a bunch of things.

So it's something I will attempt to address in a later revision of the API.

Thank you for the response, I am glad to know that this is not intentional and may be fixed later on.

For now, I was able to work around the problem by adding a feature to my client to support mapping the raw response before attempting to deserialize.

---

With respect to the e621 API collection serialization, is the API moving toward or away from envelope objects generally? I see that the posts endpoint always returns an object like { "posts":[] } instead of just [], but that makes it inconsistent with typical (non-empty result) behavior of the tag and tag alias endpoints, which return a basic JSON array. Will the posts endpoint eventually be changed to return an array as well?

mr_pacific said:
Thank you for the response, I am glad to know that this is not intentional and may be fixed later on.

For now, I was able to work around the problem by adding a feature to my client to support mapping the raw response before attempting to deserialize.

---

With respect to the e621 API collection serialization, is the API moving toward or away from envelope objects generally? I see that the posts endpoint always returns an object like { "posts":[] } instead of just [], but that makes it inconsistent with typical (non-empty result) behavior of the tag and tag alias endpoints, which return a basic JSON array. Will the posts endpoint eventually be changed to return an array as well?

As there are many cases where metadata and related objects being attached to the response are useful, it's likely to take a format closer to JSON-API where all responses have a standardized root object that holds the returned collection, most likely with a standardized name, such as results. When I get there, it will be a collaborative process with some beta testing involved.