Json API response format for non-resource data, like oAuth token


#1

Hey,

I am returning the oauth access token from my api and I am puzzled as to how to correctly do it in the jsonapi format.

Treating it as a resource seems wrong, I don’t want to return an ID for the token. Is it correct, to ignore the jsonapi format for this? How would I format it otherwise? Would I just jot it into the meta part like this?

{
  "jsonapi": {
    "version": "1.0"
  },
  "data": null,
  "meta": {
    "access_token": "Qcg6yI1a5qCxXgKWtSAbZ2MIHFChHAq0Vc1Lo4TX",
    "token_type": "Bearer",
    "expires_in": 3600
  }
}

JSON API for non-resource responses
How to handle non-resource POST request and response ? (like session login)
#2

What about this representation?

{
  "jsonapi": {
    "version": "1.0"
  },
  "data": {
    "id": "Qcg6yI1a5qCxXgKWtSAbZ2MIHFChHAq0Vc1Lo4TX",
    "type": "bearer-token",
    "attributes": {
      "expires-in": 3600
    }
  }
}

#3

Well, this does not sound bad.

I think the type would need to be Bearer as this is an official oAuth type as far as I know.
I am only worried, because the names

  • access_token
  • token_type
  • expires_in

seem to be somewhat “official” as in everybody using them. Would there be a way to keep those names and still stick to the standard?


#4

Something like this perhaps?

{
  "jsonapi": {
    "version": "1.0"
  },
  "data": {
    "id": "2015-07-29T10:09:29.000Z",
    "type": "token",
    "attributes": {
      "access_token": "Qcg6yI1a5qCxXgKWtSAbZ2MIHFChHAq0Vc1Lo4TX",
      "token_type": "Bearer",
      "expires-in": 3600
    }
  }
}

It’s really up to you! Best of luck :smiley:


How to you send a success message
#5

Hey, this is a pretty good idea. Thanks.

Can you tell me, do I need to be able to do a select with id & type to get the item to fullfill the jsonapi requirements? Or would it be enough to ensure that only one item with the id-token-combination exists?


#6

This might seem like a subtle point, but take a minute to think about it if it doesn’t click right away. The responses you return with your API are representations of your data. They aren’t the data itself.

To put a finer point on it, JSON-API doesn’t care about how you store your data. Put it a relational database, a document store, a text file, whatever. As long as you generate JSON-API compliant responses, consumers don’t have to know (and should be actively shielded from) the implementation details around how it was generated.


#7

Is there specific reason you want to use JSON-API for the auth component of your app? For any authorization calls I generally use a standard JSON content-type since they don’t form any sort of domain object.


#8

I apologise for reviving this old topic, but only just had the same problem myself…

This seems absolutely spot on, but is exactly what I see as problematic with the schema. A data object is classified as such not by its implementation, but whatever logical encapsulation the programmer wants to convey. The problem as I see it is that the object must include an id. In fact the schema says the following:

“Within a given API, each resource object’s type and id pair MUST identify a single, unique resource”

So if we’re talking about trying to represent some data that we want to represent as an object, but it may not be a single unique resource, we’re left trying to push a square peg into a round hole just to satisfy the schema.
We could always hash the contents of the data to ensure that the id is mostly unique, but at that point surely you have to wonder why we’re doing that, as it’s probably useless and confusing (if the id value of your other objects refer to the PK value in your DB for example, and can be used to fetch them).

Perhaps I’m missing something here, but it would seem reasonable for the standard to allow the dropping of the id if it no longer had any purpose and only sought to confuse the consumer (and implementer!) of the service.


#9

Wouldn’t be better in this case to honour OAuth RFC? https://tools.ietf.org/html/rfc6749#section-5.1

The parameters are included in the entity body of the HTTP response
using the "application/json" media type as defined by [RFC4627].  The
parameters are serialized into a JSON structure by adding each
parameter at the highest structure level.  Parameter names and string
values are included as JSON strings.  Numerical values are included
as JSON numbers.  The order of parameters does not matter and can
vary.
...
into a JSON structure by adding each parameter at the highest structure level.
...

That will means that response should looks like:

{
    "access_token": "Qcg6yI1a5qCxXgKWtSAbZ2MIHFChHAq0Vc1Lo4TX",
    "token_type": "Bearer",
    "expires-in": 3600
}