Should an API platform enforce only receiving JSON requests?

Question

I am building an API platform.

I have already ensured that the platform always returns JSON responses.

My question is

Should my API platform enforce the rule that all requests must be JSON? What are the benefits of making all requests to be JSON?

I understand the benefits of making all responses to be JSON as this means consistency for the client apps using the API.

I fail to see the benefits of making all requests to be JSON as well.

I am asking this because GitHub API v3 appears to be enforcing this rule.

My API platform will involve uploading of files in the requests. As far as I know, JSON requests does not work well with file uploads.

Or do I do a hybrid?

Enforce that anything NOT to do with file upload should send their requests as JSON?

And allow an exception for file upload?

Answer 1

Make a choice what formats you want to support. Detect the content type using the request's Content-type header; if it doesn't match any of your supported types, reject the request with a 415 status code (or a more generic one, like 404 or 500, depending on whether you are willing to tell the client what went wrong or not). If it does match, at least verify that the request is well-formed before doing any processing.

If you control both the client and the server, or you are in a position to determine the protocol, then it doesn't make much sense to support more than one content type for your regular messages - just specify what you expect, and reject anything else.

Also, note that it is often easier to use regular POST data instead of JSON for the request: e.g. the jQuery Ajax API makes it super-straightforward, and many of the reasons for using JSON for the response (Same Origin Policy, structured data, easy and fast to parse in javascript) often just don't apply for the request.

Answer 2

Your API needs to be able to understand the request.

How can you do this if you accept random formats.

An API consists of the definition of the formats, acceptable values contained within and the sequence in which they are exchanged.

If you wish you can specify that your API also accepts XML requests, or perhaps plain url get requests.

GitHub has specified a JSON based API and quite rightly rejects any request that is not valid JSON.

Answer 3

I think that also allowing normal HTTP formdata requests provides some practical advantages over a pure JSON API. You already mentioned uploading files, where using JSON is tricky at least; but also normal requests benefit in terms of simplicity.

HTTP already has two formats for parameter passing, why not use them?

Answer 4

I think this is a question of approach, and you are right on "failing to see the benefits" of such restriction. Your service has a defined API; some of the entries require structured data (commands and data objects), others process streams (file upload). If I see it in this way, I see no problem.

• If you have to accept something as a stream, you don't force anyone using an improper format (now JSON), but let them send you that file in the most natural way. This is not "breaking" some rule, but the simplest way to do the job. KISS.
• If you have to process data hierarchies from the client: commands and objects, yes, it is nice to give one, and perhaps the easiest way to send you hierarchies, JSON is okay. For your clients.

But for you inside the service, it is not beneficial to actually see JSON, because that is only a stream syntax and the handler components around it (the same exists for XML and perhaps other formats as well). Your codes don't need JSON, they need data hierarchies. So my advice here is to hide the fact that now you use JSON format and handlers, from all of your higher level codes. The options:

• deserialize to actual object instances within your platform,
• convert to a hierarchy of Maps, Dictionaries or alike
• or hide the actual JSON node objects behind a simple interface with getAttribute, getChildren, etc. methods.

Some time later you might be unable to force a client to use JSON, because their systems communicate through XMLs, can only use plain forms without JavaScript, or their data is actually in a database. Then you will love the concept of having JSON invisible to the rest of your code by any of the above means: you then just write the next wrapper for that XML (or HTTP request parameter package, whatever), and you are done: the same API and code can be reached through another "data language".

At least this is how I see it.