a. I don’t think this spec is the place to mandate the content of attributes as there are no semantics in the spec that rely on dates. You might want to use an OAS 3.0 spec to specify this kind of requirement – which is RFC 3339, a profile of ISO 8601.
b. I think, as a RESTful spec, that the usual meanings of HTTP status codes apply here. I haven’t seen a problem with this in practice. The spec does not support bulk operations, so there’s no need for the complication of both data and errors in the same response. There was a draft extension for bulk but it died on the vine. See the extensions tab at jsonapi.org.
c. Just as jsonapi is opinionated, so am I: Truly RESTful applications only use HTTP verbs with resources that are generally plural nouns for collections. If you think you need the equivalent of a SOAP method invocation, recast it as a new resource with attributes that track the state of the transaction and whatever business rules that trigger insider your server based on those attribute values. Using relationships you can tie that resource to the one it is related to.
d. The JSON spec allows pretty much anything as a mapping key; there’s no expectation that you’ll map a key to a direct programming language variable. For example, in Python, I would use something like result['data']['attributes']['start-date'] to reference the start-date attribute in this response:
{
"data": {
"type": "my-type",
"id": "00452381-cb1d-4198-a029-9bcc6d838a44",
"attributes": {
"name": "Data Services",
"version": "BI4.2",
"start-date": "2012-03-01"
}
}
}
Some libraries (like Django REST Framework JSON API – DJA) will automatically do camel-, snake- etc. case conversions for you. And ORM client libraries will also do the mappings. Having said that, in DJA, the mappings are usually constrained to Python’s variable names, so you wouldn’t see a hyphen.
e. I believe that is why jsonapi has a rich error object definition.
f. See above re: Dates.
g. OAS 3.0 is able to represent jsonapi. This is actually WIP for the DJA project: automated OAS 3.0 schema generation.
h. That seems out of scope for jsonapi. Security specification is already present in OAS. Our jsonapi apps use OAuth 2.0/OIDC via the Authorization header.
i. Hahaha. Seems the big competitor is actually graphql. This is my go-to argument for jsonapi: https://www.jeremiahlee.com/posts/json-api-your-smart-default/. But stuff is always changing.
All of the above are my opinions based on being a consumer of the spec. I’m sure some flames will ensue, as I’ve previously been flamed here.