Extending profiles for filters, sorting, paging, ranges, etc. about json-api

[steveklabnik]

Is there going to be an official list of methods for defining a common subset of all of the extensions (profiles) as suggestions?

Probably not. I need to re-read the profile RFC, but I think you can only have one?

should there be a place to list common profiles/meta URLs,

Ideally, profiles include the application semantics, so really, there shouldn't be a lot of commonality.

How do we avoid bloat of N metas/profiles in each response?

Anything which is used by a large number of people should become an actual addition to the spec. Think of it as 'pull up method', the refactoring technique.

Is there going to be a suggested best practice for profile URLs to contain a version number in the profile URL?

Nope. In general, media types generally aren't versioned. There's nothing stopping you from including a version somehow if you'd like; for example, you could namespace your profiles to introduce one ("profile":"http://mysite.com/v2/profile").

I think that covers everything. Let me know if I didn't.

[garysweaver]

should there be a place to list common profiles/meta URLs,

Ideally, profiles include the application semantics, so really, there shouldn't be a lot of commonality.

I don't think usually that Rails apps at least are going to be describing custom profile URLs. If someone integrates with a specific api, be it their own application's api or a specific vendor's, they won't benefit as much from some URL that describes something unless it is solely for identification and version as a sanity check that the think that they integrated with did not change.

I see much more benefit in a URL that either describes a package of functionality like a gem that alters API behavior, or it describes a specific behavior or set of behaviors (like paging using a specific URL scheme).

If it describes a package of behavior it might have a 1:1 relationship between the version of the gem and the URL, i.e. https://api.rubygems.org/restful_json/v5.0.0, such that the restful_json gem would emit that version in its response and the client could look at it and determine whether it was compatible, and if not, it may quit or complain unless it matched/fuzzy matched it. It could even have the api description of part of gemspec and rubygems.org could host the human readable description. (And that wouldn't be Ruby specific- the same could be done for Java, etc.- they'd just need their own.) This seems cool, but I don't think it is as useful, because it isn't describing specific behaviors that the client can use, and is basically not much different than application-specific integration. It also would expose what gems a vendor is using in their API, so could even be a security hole.

If it describes a specific behavior instead, it might look like https://some.standards.org.or.vendor/api/paging. Multiple gems that provide paging functionality through controller api extension (like restful_json and others) could use the same URL. Then the client would know it could just append &page=1 to the URL to get the first page of results. But, if this is done, we should really have some sort of standards organization that is ok'ing different schemes so that they were well-planned and could last longer. I think this should be done to greatly future-proof the spec. Most of the current spec could even be split into different behaviors. This would increase the size of the responses significantly, so perhaps it could be a separate single call to get a list of behaviors of the spec that could be cached in the client.

[jokeyrhyme]

Seems related to #45

[jokeyrhyme]

Oops, seems related to #21