(REST/HATEOAS) Best practices in Access Management

[David Lauzon]

Hi folks!

We're designing a large single application based on REST / Hateoas / HTML5 / Ajax / Json. Is there any best practices out there to manage the access management?  

For the Hateoas part, we're using Json-Schema to define all the possible actions (Verb + URL) on a resource. Since this file is the same for all users and all "instances" of a resource, it is cacheable.

If user has access to a resource called "Budget", he may have the permissions to perform all actions on Budget #25, but only a subset of actions for Budget #30. Since the permissions are not cacheable (or for a very short time), it feels best to design a specific web service to access the user's permissions on a resource.

So far, I am inspired by how SOP/CORS deals with this issue by using the verb OPTIONS.

But how are you guys dealing with this?

-David

[David Lauzon]

For example, User A can perform these actions on Budget #25:

GET  /budgets/25
GET  /budgets/25/incomes
POST /budgets/25/incomes

But he has only access to a subset of the actions on Budget #30 :

GET  /budgets/30
GET  /budgets/30/incomes

If the user tries a POST /budgets/30/incomes , it will get a 403 Forbidden. But this a bit obstrusive. It would be best to inform the user of its permissions on the resource before it tries a forbidden action.

Our Json-Schema looks like this:

{
  // ... (attribute definitions)

  "links": [
    {
      "rel":    "createIncome",
      "href":   "/budgets/{id}/incomes",
      "method": "POST"
    },
    {
      "rel":    "listIncome",
      "href":   "/budgets/{id}/incomes",
      "method": "GET"
    }
  ]
}

Right now the json-schema is generic for all resources of the same type. I could filter only the links that the user is allowed to access on Budget #30. But then, this means reloading the whole json-schema every time a new Budget is loaded, for just a minor difference.

I am tempted to go with a solution inspired by SOP/CORS using the OPTIONS HTTP verb. For example:

> OPTIONS /budgets/25
... response:
<  { "allowedLinks" : ["createIncome", "listIncome"] }

and for Budget #30:

> OPTIONS /budgets/30
... response:
<  { "allowedLinks" : ["listIncome"] }

Do you see problems regarding the OPTIONS approach ?

Other suggestion ?

[Markus Lanthaler]

Yep, OPTIONS isn’t cacheable and you will need two HTTP roundtrips in case the operation is supported instead of one. I would either include/remove a link dynamically depending on the users permissions or add a flag like editable if you are really concerned about the overhead of adding/removing the links.

 

 

--

Markus Lanthaler

@markuslanthaler

 

 

 

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Andrew Braae]

Without wishing to sound like a Hateoas Heretic:

1) can your application efficiently calculate all of the possible links/options? Often it can be as computationally intensive to work out whether someone can call an API in the first place as it is to actually carry out the call.

For example, perhaps in an OAuth scenario a user is allowed to call POST /budgets/10056/incomes if:

- they currently work within a group that has "budget management access"; and that group is currently active

OR

- they are an admin user

OR

- they are temporarily working on behalf of someone else who has such permissions.

The above is ridiculously contrived but my point is that in some applications - maybe not yours - it can be very expensive to work out what operations a specific caller is allowed to make (and not the sort of thing you can cache effectively) and so it might hurt your scalability at the back end to do so with each call.

2) is it efficient for you to always transfer all of these possibilities over the network, just in case the caller feels like using one of them?

In a human-driven/browsing scenario (like when you will be rendering all of those budgets on a web page and building up a dropdown menu next to each of them with all possible options) then it can be valuable to have the information you are talking about.

But in many application scenarios it's not that useful - maybe people don't tend to go poking around trying to perform random operations on budgets they don't have access to, and therefore its perfectly fine to hit them with a 403 or whatever.

But, assuming that you do indeed need to make available this Hateoas-type information along with your resource, maybe you could decouple it? i.e. include a link in the resource leading to the valid options, which you could fetch using a separate request?

That is similar to your OPTIONS idea, in that its up to the client whether they fetch it or not (and thus whether you take the hit in calculating it), but maybe using plain GET gives you a bit more flexibility if its possible for you to cache the valid options, even for a short time (as per Markus' observation that OPTIONS is not cacheable).

Cheers,

Andrew

[mca]

<snip>can your application efficiently calculate all of the possible links/options</snip>

this is *always* a cost that MUST be paid otherwise the server will fail to secure resources. implementing a hypermedia-style interface does not increase the cost of access rights computations.

<snip>is it efficient for you to always transfer all of these possibilities over the network</snip>

this is the correct question to ask. if you plan on sending *every* possible action for *every* requested resource, the cost of generating representation responses is going to be high for "sufficiently complex" cases. IME, it's rarely wise to emit all possible actions on all resources. This is rarely done for direct-human(HTML) interfaces and I don't see a reason to change this decision for APIs regardless of the interface style.

<snip>people don't tend to go poking around trying to perform random operations </snip>

always true no matter the style. no reason to change this if you start sending links ;)

<snip>include a link in the resource leading to the valid options, which you could fetch using a separate request</snip>

bingo! just as in direct-human interfaces(HTML), place the most-commonly used API options directly in the response and include a "more options over here..." link to cover all the others. and if you're design is so bad that the "more over here..." list is huge, provide paging for the poor slob that has to suffer your lack of API design skills ;)

cheers.

mca

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

--

[Philip Nelson]

"the cost of generating representation responses is going to be high for "sufficiently complex" representations

When is this true? I trying to figure out if people find this hard to reason about, i.e. the logic is expensive to write, or do you mean it is actually too many cpu cycles per request? Or maybe fetching the details needed to make the calculation is difficult?

I have a hard time coming up with either situation, but I do have a state machine technique I use that makes it fairly easy to calculate, and doesn't seem to be burning many cycles to do it. 

[mca]

Philip:

yes, this is completely domain-specific. Andrew had offered an example of what seemed to be a rather complex case (multiple group membership, temporarily acting as a proxy for another user, etc.) and i was willing to ack that there are times when computing access rights takes a handful of cycles (without trying to go into the math involved).

IME, computing access rights is not a big deal. most of the time i am using a user's identity against the URL + method (in HTTP, at least) and the cost is low. occasionally, i am forced to bixel through a list of group memberships to compute the rights. rarely do i need to account for context-specific rights adjustments based on location (are you making a request from the local coffee shop or within the firewall), too. these last few cases tend to add more cycles, but nothing i can put a hard value on.

my primary point in responding to Andrew was to point out that this computation cost is the same no matter the style of interface you implement.

not sure if this helps, but that's my experience.

cheers.

mca

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

[Andrew Braae]

In our business domain (talent management systems) the example I gave is actually not that far from reality. The cost of calculating access rights is sometimes *high*, with a fair bit of SQL required.

(That may or may not equate to bixel-ing, it is not a term I know, though I like the sound of it).

But just to respond to your last point, what I was trying to say is that you want to avoid these computation costs when you can. Yes, at a minimum you need to incur the computation cost for validating someone's call to API A at the time when they actually call API A, but best practice might be to otherwise avoid the "in advance" computation where possible (e.g. avoid the extreme case of calculating *all* operations on *all objects*).

--
You received this message because you are subscribed to a topic in the Google Groups "API Craft" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/api-craft/g30AfGiC-Tk/unsubscribe.
To unsubscribe from this group and all its topics, send an email to api-craft+...@googlegroups.com.

Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

--

Andrew Braae

CTO Talent App Store

www.talentappstore.com

abr...@talentappstore.com

IP creation: Any intellectual property created within this email message  is the property of Talent App Store Limited, unless prominently labelled otherwise within this message, or as subject to previously written agreement between ourselves. We ask that you inform us immediately if you have received this email message in error.

[Kijana Woodard]

> but best practice might be to otherwise avoid the "in advance" computation where possible

Especially when the answers can possibly (probably?) be different by the time the subsequent request is made.

<rant>

I loathe these types of "security" requirements. My years in Enterprise Development informs that most of the times these are political/turf requirements masquerading as "security". Every situation I've encountered could be solved with user visible logging and compensating actions [which you probably need both anyway]. Sure, only finance people can see finance stuff. But the levels of complexity created in the name of "security" can be insane. I saw a system with 10x the number of security _groups_ vs users. The reason for "group explosion" was that the security model was so opaque, that the admins just stuck the users [complainers] and the requested resources in new groups. And at the end of the day, the users end up hacking around all this by giving out their passwords [despite, or in spite of, policies to the contrary]. Needless to say, "can you do this" was a computationally expensive question.

</rant>

[mca]

yeah, we're totally on the same page. 

i've employed some session-based caching of access rights computation in order to cut down on request-time costs, but this is a slippery slope (as would be assumed). anyway, the cost is the cost -- that's the message.

and, FWIW, "bixeling" is my old-school habits coming through ;) pre-relational DB, the way to work through a set of related items was to work through the list in sequential order -- byte-by-byte or bix-es. sadly, i can't quickly find any slang reference online to support my memory, tho ;<

mca

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

[Andrew Braae]

Classic rant Kijana!

Though there's a lot of truth in what you say, perhaps HR software is a little different. In a giant retail organisation, where all sorts of activities are devolved down to the store level - manager, assistant manager, admin assistant, team leader of the gardening section, then throw  in that you're dealing in people's salaries, sick leave, personal grievances with their workmates, career trajectory, etc. etc. its not unreasonable to have some pretty fancy dancy org-based rules around who can see/do what.

But I'm sure that as you say, having good visibility into what was done, and some undo actions, could often mitigate this kind of craziness.

[David Lauzon]

Thank you all for your great input. I've been bixeling my thoughts ;-). And here's my answers:

@Markus:

Yep, OPTIONS isn’t cacheable

   

Good point.


@Andrew:

1) can your application efficiently calculate all of the possible links/options? Often it can be as computationally intensive to work out whether someone can call an API in the first place as it is to actually carry out the call.

You're right, in the long term this computation can become heavy. But like @Mike mentions it, the app has to pay the cost sooner or later. The access rights have to be validated during the CRUD web service call anyway.

[example] they currently work within a group that has "budget management access"; and that group is currently active    OR    they are an admin user    OR    they are temporarily working on behalf of someone else who has such permissions.

Actually, your example is pretty close to our flexibility requirements. The government agencies is one of our eventual target customers, and they are picky on granular access. To give you in idea of the size, we currently have about 100 resources and a couple hundreds more to come in the next year.

In a human-driven/browsing scenario (like when you will be rendering all of those budgets on a web page and building up a dropdown menu next to each of them with all possible options) then it can be valuable to have the information you are talking about.

Yes, the sidebar menu will be different depending on the user. However, a menu item can be expanded into several resources (for the same screen). That way we can isolate specific privileged actions into separate resources. So the actions (or verbs) on a resource is the smallest unit of granularity that we currently support. We divide a resource into multiple resources as needed for that purpose.

But in many application scenarios it's not that useful - maybe people don't tend to go poking around trying to perform random operations on budgets they don't have access to, and therefore its perfectly fine to hit them with a 403 or whatever.

The application the client is currently using is doing exactly that. However, it adds a value to the user experience if we **can** hide features that the client cannot use.

But, assuming that you do indeed need to make available this Hateoas-type information along with your resource, maybe you could decouple it? i.e. include a link in the resource leading to the valid options, which you could fetch using a separate request?

That is similar to your OPTIONS idea, in that its up to the client whether they fetch it or not (and thus whether you take the hit in calculating it), but maybe using plain GET gives you a bit more flexibility if its possible for you to cache the valid options, even for a short time.

Interesting idea, but I am not sure HTTP caching is a good way to cache the permissions since we have no way to invalidate an HTTP cache (whenever a change occurs).

Since the permissions do not change frequently, it seems best to cache all the permission records on the application side, and then reload the changes when needed.

[David Lauzon]

@Mike:

just as in direct-human interfaces(HTML), place the most-commonly used API options directly in the response and include a "more options over here..." link to cover all the others

This seems like a good evolution of the concept. The "more options over here" is in fact compatible with the OPTIONS web service (or @Andrew's cacheable GET version).


@Kijana:

Especially when the answers can possibly (probably?) be different by the time the subsequent request is made.

It should be rare that permissions changes, but whenever it happens sending a 403 is fine.

About your security rant, I agree with you. For that matter, we're trying to keep the security model as KISS-able as possible for the context.

well, thanks a lot folks!

[Kijana Woodard]

One thing to consider when security gets complicated: what they're actually asking for is a firm wall between internal teams. Consider separate deployments for high level security concerns. If necessary, make  sharing assets/data/resources between deployments an explicit, highly visible step.

In the end, it's easier to reason about operationally and is fundamentally more secure. It also takes out a lot of computation. The cost is maintaining multiple deployments. Automation is your friend there. Another benefit is that you can upgrade the less critical installations first to serve as guinea pigs, errr, early adopters.

--

[wiki1000]

Hello,

First I dont see any reason to use JSON since the Link Header has enough power to convey what you need.
Why are you liking so much all these double quotes guys?

Second, HATEOAS requires navigation and any operation on the link </budgets/25/incomes> shall first
requires a GET on link </budgets/xx> which will return, according to HATEOAS principles:

Link: </budgets/25/incomes>; rel=incomes;allow=POST;allow=GET
or
Link: </budgets/30/incomes>; rel=incomes; allow=GET

GET (and its returned headers) is cacheable.

Your trick with Options is specially awful and breaks the URI opacity principle, while imposing anyway an additional request.
An additional request is simply unavoidable if you want to avoid the error.

Another point is that you should not expose the template
</budgets/{id}/income>
precisely for the reason above.

Note: I still dont understand the purpose of HAL and all the equivalent formats: there are no ways to reasonably describe in advance what will happen during an hypermedia navigation.

Cheers,

[David Lauzon]

Hello wiki1000,

On Tuesday, January 27, 2015 at 8:29:38 AM UTC-5, wiki1000 wrote:

First I dont see any reason to use JSON since the Link Header has enough power to convey what you need. 
Why are you liking so much all these double quotes guys?

I wasn't aware of the Link header ([1], [2]). I agree that having the links in the headers of the original request is clearer. But it also means that we have to send those headers on every request. Still, for most use cases, it seems like a better idea to use the Link header. For our use case however, we can have up to 30 links per resource. Adding all those headers now make the header size larger than the payload size.

[1] http://www.w3.org/wiki/LinkHeader

[2] https://tools.ietf.org/html/rfc5988

The advantage of putting the links in the json schema is that the schema is cacheable, and remains the same for every resource instance of the same type (e.g. /budgets/25, /budgets/26, etc.). Also the format of the links in the json-schema are standardized, meaning generic clients can be used to browse the API.

Link: </budgets/25/incomes>; rel=incomes;allow=POST;allow=GET
or
Link: </budgets/30/incomes>; rel=incomes; allow=GET

I've seen that a few attributes (like rel) have been standardized in RFC 5988. But haven't found any reference for the "allow"... is this standardized somewhere / recognized best practice?

Your trick with Options is specially awful and breaks the URI opacity principle, while imposing anyway an additional request.
An additional request is simply unavoidable if you want to avoid the error.

Another point is that you should not expose the template
</budgets/{id}/income>
precisely for the reason above.

I'd like to understand better your point. The URI Template is an IETF standard ([3]).

[3] http://tools.ietf.org/html/rfc6570

Why is it a bad idea?

 

Note: I still dont understand the purpose of HAL and all the equivalent formats: there are no ways to reasonably describe in advance what will happen during an hypermedia navigation.

1) The main purpose is to describe the payload being exchanged by the client and the server (is this field an integer/string, required or not, etc.).

2) Then, they also allow you to describe the HATEOAS links. Yet, I agree with you that using the Link header is a better idea when the number of links is relatively low

3) Knowing what are the links, and knowing what links are available to you are 2 different things. The links are most likely the same for everyone, but not everyone has access to it. When building the GUI, we can hide the options that the user has not access to. This seems to fit what the OPTIONS method was created for. Do you have a better idea?

Regards,

[wiki1000]

Hello David,
There is also a draft extending the Link parameters
http://tools.ietf.org/html/draft-nottingham-link-hint-00
It mentions the "allow" convention which seems quite natural.
It mentions also the "accept-post" and "accept-patch" conventions which can also be very useful.
I consider that a simple use of the parameter is allowed (no need for this ugly JSON, although possible).

About HAL, UBER etc
data contained in Headers is cached as well as the content, it is not an argument for using JSON content.
You cannot say that this awful set of private different formats is "standardized" in any way: they are just multiple instances of the same bad idea, in competition for obscure reasons.

About the excessive number of links to advertize: I would answer that 30 links is not too much data, if this data is really useful, and if not perhaps there are too many and shall be reduced. Anyway I dont think such an answer is really useful, sorry to propose it.

I fully agree that Uri Template is a very useful standard. What I suggested is that advertizing the link /users/{id}/income from another resource than /users/{id}  breaks the context you wanted to create, in order to specifically specify a property of one of the possible templated links. I suggested then to apply HATEOAS precisely where it is meaningful: not at the root of the site tree, but in the context of a given parent link.


About the OPTIONS method, I would blindly believe a known guru of the domain:
https://www.mnot.net/blog/2012/10/29/NO_OPTIONS

I am not sure to understand your last question since I precisely suggested to use the Link Header for publishing in context the data you need, and only when you need it.

Bye !

[Mike Kelly]

On Mon, Feb 2, 2015 at 4:38 PM, wiki1000 <wiki...@gmail.com> wrote:

Hello David,
There is also a draft extending the Link parameters
http://tools.ietf.org/html/draft-nottingham-link-hint-00
It mentions the "allow" convention which seems quite natural.
It mentions also the "accept-post" and "accept-patch" conventions which can also be very useful.
I consider that a simple use of the parameter is allowed (no need for this ugly JSON, although possible).

About HAL, UBER etc
data contained in Headers is cached as well as the content, it is not an argument for using JSON content.
You cannot say that this awful set of private different formats is "standardized" in any way: they are just multiple instances of the same bad idea, in competition for obscure reasons.

I'd like to this the antisocial tone of this email is inadvertent, although my assumption is that it is not.

You haven't done a good job of explaining exactly why including links in the body is "ugly" or all of the formats that afford that are "awful" and based on a "bad idea". Those are quite strong words, I'm fascinated to hear more about why you are so rabidly opposed...

Cheers,

M

[wiki1000]

I'd like to this the antisocial tone of this email is inadvertent, although my assumption is that it is not.

Well, I agree, but this is due to some irritation: JSON impose to quote attribute names for obscure reasons, this is painful and ugly (not beautiful). At the same time, you have the Link Header spec, almost fully standardized, available and strangely unknown: why? This is irritating.
 

You haven't done a good job of explaining exactly why including links in the body is "ugly" or all of the formats that afford that are "awful" and based on a "bad idea".

 

- JSON is awful (double quoted attribute names)
- JSON based formats are not type checked in general
- The formats are multiple (instead of being unique)
- They are used to duplicate existing things (HTML itself and it is irritating, the Link Header, irritating too, and WADL now considered bad).

HTTP + its headers + HTML+RDFa is a way to express EVERYTHING in a clean and standard way.
Why considering something else ?

Another good practice, very useful and comparable in its simplicity with the use of the Link header:
the text/uri-list  media type, allowing to transfer resources by reference in a very simple way.
Using JSON to duplicate this simplicity is an absolute scandal !

Cheers.

[Mike Kelly]

On Wed, Feb 4, 2015 at 9:35 AM, wiki1000 <wiki...@gmail.com> wrote:

I'd like to this the antisocial tone of this email is inadvertent, although my assumption is that it is not.

Well, I agree, but this is due to some irritation: JSON impose to quote attribute names for obscure reasons, this is painful and ugly (not beautiful). At the same time, you have the Link Header spec, almost fully standardized, available and strangely unknown: why? This is irritating.

For me it's not irritating, it's interesting... and sort of backs up claims that the Link header is, in practice, less effective.

 

 

You haven't done a good job of explaining exactly why including links in the body is "ugly" or all of the formats that afford that are "awful" and based on a "bad idea".

 

- JSON is awful (double quoted attribute names)
- JSON based formats are not type checked in general
- The formats are multiple (instead of being unique)
- They are used to duplicate existing things (HTML itself and it is irritating, the Link Header, irritating too, and WADL now considered bad).

HTTP + its headers + HTML+RDFa is a way to express EVERYTHING in a clean and standard way.
Why considering something else ?

Another good practice, very useful and comparable in its simplicity with the use of the Link header:
the text/uri-list  media type, allowing to transfer resources by reference in a very simple way.
Using JSON to duplicate this simplicity is an absolute scandal !

JSON is ubiquitous (parsers available in majority of modern languages). It's very simple. It's designed specifically for transferring data in machine readable form.

HTTP headers have practical size limitations. Some network proxies do strange things to headers. Link header parsers are less ubiquitous. Some clients don't have access to response headers (JSONP).

RDFa carries with it all of the usual RDF baggage. Most of that baggage has nothing to do with the simple objective of representing a link from the current represented resource to some other URI.

The web/API communities are large, there will probably be very good reasons this is the case.

Cheers,

M

[Mark Derricutt]

On 6 Feb 2015, at 5:56, Mike Kelly wrote:

> For me it's not irritating, it's interesting... and sort of backs up claims that the Link header is, in practice, less effective.

One (potential) problem with headers can be traced back to one of the problems SOAP faced, certain firewalls/proxies would strip out unknown headers and could be the cause of many a problem. I don't think this is really the case anymore but that could lead to folk favouring keeping such things in the payload body - also, from memory several HTTP libraries or XMLHttpRequest APIs made it difficult ( or even impossible ) to access the headers of a response - this again I believe may be a thing of the past ( I believe Flash and ActionScript's libraries were extremely limited here ).

IMHO Headers work really well if you're dealing with mixed media type resources, as you could put Link's against PDF, MP3 representations and continue to have a consistent API model.

Personally, as someone whose often working more at a library/framework level, I'd consider exposing a consistent API for looking for links that abstracted both the HAL + Header level and treat header based links as being the same as top level <resource/> links.


--
Mark Derricutt
http://www.theoryinpractice.net
http://www.chaliceofblood.net
http://plus.google.com/+MarkDerricutt
http://twitter.com/talios
http://facebook.com/mderricutt

[Pete Johanson]

On Feb 5, 2015 5:50 PM, "Mark Derricutt" <ma...@talios.com> wrote:
>
>
> Personally, as someone whose often working more at a library/framework level, I'd consider exposing a consistent API for looking for links that abstracted both the HAL + Header level and treat header based links as being the same as top level <resource/> links.

Exactly this! That is the approach my angular-hy-res (and hy-res core library) takes. The exact mechanism of link delivery can in some regards be treated as an unimportant implementation detail.

-pete

[wiki1000]

Hello all.
I dont see any problem with any kind of use of HTTP headers in theory and in practice. Sorry.
The fact that some (who exactly?) claim that it is "less effective" does not terrorize me at all.
HTTP headers can be cached and they can be manipulated in Javascript from XmlHttpRequest without any kind of difficulty.
JSONP shall be considered deprecated. CORS has been cited by the initiator of the thread.

About using RDFa as a microformat, I dont see any rational argument for not using it. There are around 1 billion web pages using it already without any kind of fundamental problem about the RDF XML syntax, which is NOT used by RDFa anyway. You can use it to convey any kind of structured, typed, graph of data objects, plus in some cases, the qualification of some links, which remains perfectly possible. Devoting a whole media type for such an humble task is not reasonable in my opinion.

Sorry to be vehement like that, but I am sure to not be alone thinking that.
Too many people loose their time using unnecessary bloated  libraries (I loved the suave allusion made by Mark Derricut to problems encountered by SOAP users)  covering cases which shall be deprecated.
Think to the (too high) percentage of the web  still using SSLv1 or worse, Internet Explorer for browsing: kids cant wait !

[darrel...@gmail.com]

wiki1000,

I’m going to give you pretty much the same answer I gave to someone on the hypermedia-api list who is “vehemently” saying that people are wasting their time considering HTML as a viable hypermedia format and everyone should be using “Linked data RDF”.

The fact that you like using Linked Headers is awesome.  I’m a huge fan of RFC 5988.  I’m also a fan of the simplicity of text/uri-list.  Go use it to build awesome stuff and show us how you did it.

If you don’t like JSON, don’t use it.  That’s cool.  YAML is really cool.  I also happen to like XML (once you kill the namespaces 😊).  Plain text formats are way underused.  application/sql FTW!

The uniform interface allows the web to interoperate with all different kind of formats.  We don’t need to waste effort and emotional energy debating which is the best.  Use what works and get stuff done. 

This REST/API community has  come a long way in the past few years in being more open and accepting of a wide range of approaches.  I’m not going to let us fall into some kind of nasty turf war over whose format is best.

Darrel

Sent from Surface

[Sam Ramji]

wiki1000, this is the moderator of API Craft.

You are free to make great technical points, including highly subjective ones.

Please make your tone more collegial.  You are out of bounds of the standards of this community.

[wiki1000]

Hello Darrel
Sorry to be "vehement", but I prefer simple solutions.

I dont like JSON, and I dont like YAML too (generating it counting white spaces is a real pain).

But however, we do not disagree completely: we share a common consideration for:
Link Headers: http://tools.ietf.org/html/rfc5988
Uri Templates : http://tools.ietf.org/html/rfc6570
text/uri-list media type : https://www.ietf.org/rfc/rfc2483.txt

I would add:
profile attribute of application/xhtml+xml  : https://www.ietf.org/rfc/rfc3236.txt

I would add also the strangely abandoned:
uri hints drafts : http://tools.ietf.org/html/draft-nottingham-link-hint-00
link template : http://tools.ietf.org/html/draft-nottingham-link-template-01

There is also http://tools.ietf.org/html/draft-nottingham-json-home-03
where respected expert unfortunately advocates in favor of JSON and against HTML (sigh)

I would humbly recognize that I dont know the exact status of all these draft propositions. Perhaps people here know.

I only use the allow, accept-post, accept-patch link parameters.

Good Luck JSON and YAML people !

Cheers.

[darrel...@gmail.com]

Wiki1000,

I hear you.

Here is my implementation of URITemplates

https://github.com/tavis-software/Tavis.UriTemplates

my implementation of Web Links, Link Headers based on RFC 5988.  And also an implementation of Link Hints.

https://github.com/tavis-software/Tavis.Link

My implementation of JSON-Home parsing library

https://github.com/tavis-software/Tavis.home

I also have also have implementations of parsers for  JsonPointer, JsonPatch and Http Problem.

My perspective is that once you capture the semantics of simple media type in a parsing library, whether it uses curly braces or angle brackets on the wire is completely irrelevant.  It’s the semantics that are important.

I’m 100% with you on the idea of keeping media types simple but we need to prove ourselves by doing and creating, not endless debating.

Darrel

Sent from Surface

[wiki1000]

Hello Darrel,
All is clear, you win.
However we have now to conclude about the programming language : what about JAVA ?

[Tom Christie]

 > However we have now to conclude about the programming language : what about JAVA ? 

Probably not a productive route for this thread to go down.

Service design shouldn't be tightly coupled to the language it happens to be implemented in.

Let's keep this list for discussing API design, not for starting discussions on programming language preferences.

[Sam Ramji]

+1

Sam Ramji | ramj...@gmail.com | +1-510-913-6495

[darrel...@gmail.com]

Tom, Sam,

I think Wiki1000’s reference to language was in response to me linking to projects that I have worked on that help support building APIs.  The libraries I have built are in C# and therefore only useful to developers working on the .Net platform.

I think the question was aimed at identifying similar libraries that are available for developers working on the JVM, as opposed to inferring that different techniques should be used for different languages, which is obviously not desirable.

To address what I think is the question, unfortunately I can’t really help specifically, other than to say that I do know there are a number of talented developers working in Java on API related libraries.  Hopefully others who are more familiar with that ecosystem could contribute to the conversation.

If I misunderstood the intent of the question, my apologies.

Regards,

Darrel

[Sam Ramji]

Your comment is a testament to your fair-mindedness, Darrel.  You have repeatedly proved your thoughtfulness and consideration.

wiki1000 bears the burden of history in this case based on their 9+ months of participation over less than a dozen messages.

API Craft is a place to have conversations based on well-formed communication, authored by practitioners who are trying to solve active problems.

It is not a place for vagueness, paper tigers, or invitations to flame wars on topics regarding a "one true way."  What we have seen in the last 4+ years is a community built on "think twice, email once" which values each of us and considers the time we spend reading the emails as a community of >5300 people with over 1000 topics in our group history.

Namasté.

Sam Ramji | ramj...@gmail.com | +1-510-913-6495

[wiki1000]

Hello Darrel,
Sorry for joking. I w

[wiki1000]

Hello Darrel,
Sorry to all for this bad joke.
I dont care at all about programming languages of course, and I apologize for the deliberate misunderstanding.
The code published by Darrel is perfectly understandable and usable as such.
Thanks a lot Darrel, you are really kind with bad guys like me and deserves a lot of respect for that. Sorry again.