Multiple resources for "similar" objects or one resource and encapsulated objects

[Roland Hochmuth]

I was wondering if there were any recommendations on how to handle conceptually similar resources. In the specific API that I'm working on there are credentials, such as username-password credentials and tokens. Conceptually they are similar in that they are credentials. However, the actual objects are different. For example, one object has username and password fields and another has a token.

There are broadly two ways to model this.

1. Create distinct resources for each object. E.g. /passwords and /tokens resources. In this case the client has to deal with different endpoints for each credential type, but the resources are the actual objects.
2. Create one resource that has a credentialType, version and credentials field that allows the actual object in the document to be specified. E.g. A /credentials resource which could contain either a password or token object. This can be modeled in OpenAPI with the oneOf keyword.

A few things to consider would be API simplicity/complexity, testability, documentation.

Just interested to hear thoughts on this.

Regards --Roland

[Fredrik Sjöblom]

I have found "profiles" to be a good concept for that type of resources, that is profiles as defined by:
https://tools.ietf.org/html/rfc6906

Then again I don't I tend to think in terms of endpoints and instead focus more on Hypermedia aspects of REST API's and link relations.

But especially the way profiles are used to hint about the expected semantics of resource in generic media types like hal+json is a convenient way to model a mixed collection of similar resources served from the same endpoint. https://tools.ietf.org/html/draft-kelly-json-hal-08#section-7.1

For example hinting about a resource profile for a link relation or indicating a resource own profile on the self link, gives the necessary information for clients to know what to expect.

Basically a profile is something you can append to almost any generic media type or as a separate hint, either with an actual link withe the relation "profile" on the resource it self or some other channel before even requesting the resource, similar to the "profile" property on links in hal+json.

But if there are no common capabilities or properties between the resources, and you don't need to return them in a mixed collection, then it might actually be better to separate them. And if the resources are not backed by the same set of unique ID's it might get a bit cumbersome to encode the type as part of the item ID's.

(There is also a working draft on content negotiation based on profile https://www.w3.org/TR/dx-prof-conneg/)

   Regards

   -Fredrik

[Erik Wilde]

hello all.

On 2021-02-18 22:37, Fredrik Sjöblom wrote:
> Basically a profile is something you can append to almost any generic
> media type or as a separate hint, either with an actual link withe the
> relation "profile" on the resource it self or some other channel before
> even requesting the resource, similar to the "profile" property on links
> in hal+json.

i have to do my usual thing here and step in and say that this is not
the intended use of RFC 6906. the intended use is to use profile in the
sense of HTML: constrain/extend the base semantics of a media type
without layering a completely different layer of semantics on top of it.

i'll shut up, but i just wanted to clarify that point. cheers,

dret.

--
erik wilde | mailto:erik....@dret.net |
| http://dret.net/netdret |
| http://twitter.com/dret |

[Fredrik Sjöblom]

Appreciate the clarification.

Unfortunately the concept is a really good fit for conveying implementation specific semantics when using generic media types like json or hal+json.

Might be a somewhat pragmatic approach in that sense, but I think it gets the job done in a somewhat elegant way.

   Regards,

   -Fredrik