Anyone using RAML?

[snow6oy]

Hello,

My company currently uses WADL as a means of defining our API designs. WADLs are ok but they have limitations [1].

RAML[2] looks like it could help us with features such as: inheritance, documentation and authentication .. that are absent from the WADL spec.

Does anyone have any real-world experience of using RAML that they could share?

Thanks,

Gavin

[1] http://blog.fnarg.net/2013/06/24/are-wadls-yesterdays-news/

[2] http://raml.org/spec.html

[André Tavares]

Hi,

I gave it a try recently when designing (and iterating over that design) with a team of people in order to have a standardized way of describing the APIs. We have a Wiki page where this RAML description lives and is considered the "law".

From what I can say, the learning curve (at least for the common scenarios) is very small and people catch-up fast and like it! IMHO the limitations of YAML start when the API description becomes too big and you get lost in it... I know there are some tools for editing the RAML YAML, but haven't used them. The only tool I did use was the RAML api-console (that reads the spec and outputs a browsable API "documentation") and it worked great!

I know it ain't much, but hope it helps :)

PS- Perhaps this won't "help", but Swagger is about to release version 2.0 with its take on top-down approach to describing APIs. Since it is the most used(?), stable(?) and with the best/tested tooling(?) of all the api definition toolkits, I am kind of looking forward to it.

[snow6oy]

Hi Andre,

Thanks for the feedback. The single-point-of-truth is a responsibility that we currently allocate to The WADL, so it's reassuring to hear that you're able to do the same with RAML. I haven't looked too hard at Swagger, but some of my colleagues are advocates. I will look out for v2.

Gavin

[Dietrich Schulten]

Entirely different point of view: Joe Gregorio pointed out that WADL is a step in the wrong direction because it leads you to design custom, brittle media types and interactions. http://bitworking.org/news/193/Do-we-need-WADL. Although there is no general-purpose standard hypermedia type yet, there are several drafts, like hal, uber, hydra, siren. There is also atom and collection+json.
Did you check if they cover your needs?

--
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.

[sno...@gmail.com]

Interesting point. My work with Collection+JSON and Uber is ongoing and leading towards a messaging style implementation on a private network. The interest in RAML is more application-centric and external facing.

Gavin

-- sent from a handheld device --

---

From: Dietrich Schulten <dietrich...@googlemail.com>

Sender: api-...@googlegroups.com

Date: Mon, 7 Jul 2014 19:23:47 +0200

To: <api-...@googlegroups.com>

ReplyTo: api-...@googlegroups.com

Subject: Re: [api-craft] Re: Anyone using RAML?

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/zboTwcsfDus/unsubscribe.
To unsubscribe from this group and all its topics, send an email to api-craft+...@googlegroups.com.

[Saurabh Nanda]

We're doing some PoC specs with RAML & Swagger, so our understanding of both is limited.

The first few issues that we hit to RAML:

* The date format does not support iso8601
* No way to to define custom formats for queryParameters (Swagger supports this, I think)
* Tooling does not validate live responses OR sample formats against the json-schema (or XML schema).

Saurabh.

[mca]

HAL, UBER, Cj, Siren, etc. play a different role than WADL, RAML, etc.

those in the first group are runtime representation formats

those in the second group are design/build time description formats

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

[David Biesack]

We are also in the middle of an evaluation of Swagger, RAML, etc.

My main takeaways with RAML (with the caveat that I am still learning these, so there may be features/capabilities which I'm missing) :

Pros:

• The ability to reuse elements (whether through simple !include constructs or more structurally with traits) is very nice.
  
• The nested structure is very nice; when you have

   /models 

   /models/{modelId}

   /models/{modelId}/relationships

  you only have to document the URI parameter {models} one time, unlike Swagger where there is no connection 

  between these

 

• There is active work on various RAML related projects
  

Cons:

• YAML is tedious, especially when there is nested content, or (extensive) documentation. I've not yet tried the API designer.
  
• I'd like to pursue some means to store the documentation/descriptions externally with a docRoot URL and have the system automatically pull in doc based on the current element name.
• Like WADL or Swagger, there is no first class modeling of link relations/HATEOAS I'd like to be able to document what link relations are associated with various resources and what those link relations mean.
  
• RAML is not extensible. Unlike Swagger which uses a forgiving parser (for Swagger UI), the RAML tools  do not allow you to add additional attributes to augment the domain model 
  
• Tools need lots of improvement (API console, java raml parser, etc.)
  
• Doc needs improvement; the tutorial leaves out too much and the spec is too hard to consume/navigate.
  
• The specification for using schema is imprecise and appears inflexible (i.e. does not work well with schema emitted from JAXB schemagen)
  

Not all of these Cons are strictly dings on RAML itself as an API modeling language, but rather the RAML ecosystem, so many of them can be overcome.

djb

[Darrel Miller]

Mike,

Do the first group have to be design time only? I've been toying with
the idea of writing some media type parsers for WADL,RAML, SWAGGER et
al and seeing how they would work as a home document discovery page.
Is there a fundamental reason why they couldn't be used for runtime
discovery?

Darrel

>>> On Friday, 4 July 2014 16:40:19 UTC+2, snow6oy wrote:
>>>>
>>>> Hello,
>>>>
>>>> My company currently uses WADL as a means of defining our API designs.
>>>> WADLs are ok but they have limitations [1].
>>>>
>>>> RAML[2] looks like it could help us with features such as: inheritance,
>>>> documentation and authentication .. that are absent from the WADL spec.
>>>>
>>>> Does anyone have any real-world experience of using RAML that they could
>>>> share?
>>>>

[mca]

right - quite possible to use these description documents at runtime. IME, the current designs don't lend themselves well to this, but that doesn't mean 1) i am right or 2) we couldn't find other descirption formats that DO work well at runtime.

i'd love to see some work in this space.

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

[Darrel Miller]

My perspective was that people are already creating these design
formats. Wouldn't it be cool to be able to leverage that existing
work to generate a home document. Even if they are not the most ideal
format.

I've worked with json-home quite a bit and only being able to have one
instance of a particular link relation does make sense if you are
prepared to swallow the entire hypermedia pill but it doesn't work
well for a discovery document for URL based APIs.

Maybe I'll bump this up my to-do list a bit and maybe I'll have
something to show at api-craft or Restfest.

Darrel

[mca]

all sounds interesting....

what you describe sounds like *generation* of description docs. are you then also talking about a client that *consumes* the description doc at runtime?

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

[Darrel Miller]

Yes. I am specifically talking about client code that consumes the
description doc and allows the client to discover how and where to
make HTTP request. Not code gen. Pure runtime discovery. No idea
how feasible it is, but it is worth trying.

Darrel

[mca]

love it.

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

[Kin Lane]

Go Darrel Go!! ;-)

Kin Lane (API Evangelist)

kin...@gmail.com

@kinlane

--

apievangelist.com

apicommons.org

apivoice.com

--

[Markus Lanthaler]

On 8 Jul 2014 at 20:47, Darrel Miller wrote:
> Yes. I am specifically talking about client code that consumes the
> description doc and allows the client to discover how and where to
> make HTTP request. Not code gen. Pure runtime discovery. No idea
> how feasible it is, but it is worth trying.

Funnily enough I "pitched" exactly the same idea a couple of weeks ago to Uri (RAML). In my opinion RAML and Swagger can be seen as hypermedia documents that can be used at runtime (with most hypermedia controls being templated links). The problem, however, is IMO that all these approaches rely way too much on meaningless URL structures and string tokens that can't be (unambiguously) reused across APIs.

Hydra, on the other hand, is an approach that can be used as *description* that can also (and should) be consumed at *runtime*. Furthermore, it can be used to generate human-targeted documentation. The way it achieves this is by identifying each concept unambiguously with a URL. Reusing concepts, such as e.g. the ones defined by schema.org, across APIs thus becomes trivial.

Looking forward to discuss this further at API Craft in a couple of weeks


Cheers,
Markus


--
Markus Lanthaler
@markuslanthaler

[Darrel Miller]

Markus,

I realize these are not ideal formats for my purpose because I would
be using them in a way they were not originally intended. However,
they have traction, because they do deliver what API developers
currently want. Whether that is what they actually need is a
completely different question :-)

My opinions on formats like JSON-LD and vocabularies like Hydra are
summarized in this blog post
http://www.bizcoder.com/please-no-more-generic-hypermedia-types

The main problem I have when skimming the Hydra documentation is that
I see a meta language for describing links and HTTP operations. I
already have RFC 723X and RFC 5988. I really don't feel the need for
a meta language. Having a standardized serialization language doesn't
really get me any closer to a solution to my business problem. I want
formats that actually convey some application semantics. I want a
format that "does something", not a format that says "you can do
anything with this". But that's just my style, not a criticism of any
alternative approach.

I may not be the biggest fan of description formats like WADL, RAML,
SWAGGER, etc, but they do have a distinct purpose. Amongst other
things they identify the resources that exist in my API.

Darrel

[Ruben Verborgh]

Hi Darrel,

> The main problem I have when skimming the Hydra documentation is that
> I see a meta language for describing links and HTTP operations. I
> already have RFC 723X and RFC 5988. I really don't feel the need for
> a meta language.

As a frequent user of the Hydra Core Vocabulary, I disagree with that.
The Vocabulary offers a generic way of expressing hypermedia controls,
which clients can use to advance the application state
(and operations to change the resource state).

> I want formats that actually convey some application semantics. I want a
> format that "does something", not a format that says "you can do
> anything with this".

Exactly what Hydra does.

Ruben

[Markus Lanthaler]

Hi Darrel,

On 8 Jul 2014 at 22:55, Darrel Miller wrote:
> I realize these are not ideal formats for my purpose because I would
> be using them in a way they were not originally intended. However,
> they have traction, because they do deliver what API developers
> currently want. Whether that is what they actually need is a
> completely different question :-)

:-) It would actually be interesting to know how many APIs actually use things such as RAML or Swagger and for what reasons they use it. I'd say the vast majority of APIs is built without any of these approaches.

> My opinions on formats like JSON-LD and vocabularies like Hydra are
> summarized in this blog post
> http://www.bizcoder.com/please-no-more-generic-hypermedia-types

I fully agree that there's too much fragmentation. My answer would be that currently JSON-LD (and perhaps OData) is the only official standard in this space and widely used by Google, Microsoft, the BCC and the likes. I do, however, not see much in that blog post that applies to JSON-LD or Hydra. Yeah, JSON-LD is generic, so is text/html and application/x-www-form-urlencoded which you cite as things that work.

You cite a number of " Examples of potential media types" and urge "developers who do have experience building hypermedia types working on these kinds of focused media types instead of creating competing, one-size-fits-all formats". My question would be. What's the difference between having a single media type with multiple vocabularies compared to multiple media types that all share the same underlying serialization format, i.e., JSON? Talking about JSON-LD specifically, you have the advantage that it has a well-defined, graph-based data model. The consequence is that you can process/query all data in a uniform way instead of having write special code for each new application domain.

> The main problem I have when skimming the Hydra documentation is that
> I see a meta language for describing links and HTTP operations. I
> already have RFC 723X and RFC 5988. I really don't feel the need for
> a meta language. Having a standardized serialization language doesn't
> really get me any closer to a solution to my business problem. I want

Oh it does. It gets you closer by one layer. You don't have to write parsers for dozens of media types.

> formats that actually convey some application semantics. I want a

Why do they have to be bound to rigid media type identifiers that can't be combined (in a single representation I mean). Why can't they live on a level on top of the serialization format? Why can't those semantics not be identified with URLs as every other resource is on the Web?

> format that "does something", not a format that says "you can do
> anything with this". But that's just my style, not a criticism of any
> alternative approach.

Same here. I obviously have a different opinion but I would like to learn from your experiences and understand why you came to these conclusions.

> I may not be the biggest fan of description formats like WADL, RAML,
> SWAGGER, etc, but they do have a distinct purpose.

Which in your opinion is?

> Amongst other things they identify the resources that exist in my API.

So they are (templated) sitemaps? That's not how they have been used till now... so that can't be the reason for the traction they have.



--
Markus Lanthaler
@markuslanthaler

[Darrel Miller]

Hey Ruben,

Thanks for your input,

On Wed, Jul 9, 2014 at 3:53 AM, Ruben Verborgh <ruben.v...@ugent.be> wrote:
> Hi Darrel,
>
>> The main problem I have when skimming the Hydra documentation is that
>> I see a meta language for describing links and HTTP operations. I
>> already have RFC 723X and RFC 5988. I really don't feel the need for
>> a meta language.
>
> As a frequent user of the Hydra Core Vocabulary, I disagree with that.
> The Vocabulary offers a generic way of expressing hypermedia controls,
> which clients can use to advance the application state
> (and operations to change the resource state).

Would it be possible to give me an example of a hypermedia control
with Hydra that would not be trivial to do with something like HAL,
and a extension link relation?

>
>> I want formats that actually convey some application semantics. I want a
>> format that "does something", not a format that says "you can do
>> anything with this".
>
> Exactly what Hydra does.
>

The Hydra docs describe the purpose as "Hydra is a lightweight
vocabulary to create hypermedia-driven Web APIs". That sounds very
generic to me. The problem is, I never sit down and say "I want to
create a hypermedia driven Web API". That's never my goal. I usually
have a business problem I want to solve.

Maybe I just need to spend more time reading.

Darrel

[Mike Kelly]

On Wed, Jul 9, 2014 at 11:39 PM, Markus Lanthaler
<markus.l...@gmx.net> wrote:
>> My opinions on formats like JSON-LD and vocabularies like Hydra are
>> summarized in this blog post
>> http://www.bizcoder.com/please-no-more-generic-hypermedia-types
>
> I fully agree that there's too much fragmentation. My answer would be that currently JSON-LD (and perhaps OData) is the only official standard in this space and widely used by Google, Microsoft, the BCC and the likes. I do, however, not see much in that blog post that applies to JSON-LD or Hydra. Yeah, JSON-LD is generic, so is text/html and application/x-www-form-urlencoded which you cite as things that work.
>
> You cite a number of " Examples of potential media types" and urge "developers who do have experience building hypermedia types working on these kinds of focused media types instead of creating competing, one-size-fits-all formats". My question would be. What's the difference between having a single media type with multiple vocabularies compared to multiple media types that all share the same underlying serialization format, i.e., JSON? Talking about JSON-LD specifically, you have the advantage that it has a well-defined, graph-based data model.

The problem for is that most people do not consider that an advantage
because they are not looking for a graph-based data model. So you have
a whole bunch of complexity in the format dedicated to a small subset
of people that do want this, which is obviously not a good design for
a general purpose media type.

Cheers,
M

[Markus Lanthaler]

On Thursday, July 10, 2014 2:24 PM, Mike Kelly wrote:

> On Wed, Jul 9, 2014 at 11:39 PM, Markus Lanthaler wrote:
> > Talking about JSON-LD specifically, you have the advantage that it has
> > a well-defined, graph-based data model.
>
> The problem for is that most people do not consider that an advantage
> because they are not looking for a graph-based data model. So you have
> a whole bunch of complexity in the format dedicated to a small subset
> of people that do want this, which is obviously not a good design for
> a general purpose media type.

IHMO it's very weird to talk about hypermedia and "reject" graphs. The whole idea of hypermedia is that you create a graph of documents/data/... As soon as you introduce links you inevitably end up creating a graph. You can of course try to hide that fact by flattening the graph when serializing it but that doesn't change the fact.


--
Markus Lanthaler
@markuslanthaler

[Mike Kelly]

There's a difference between the graph between related resources
(created by linking them together) and using a graph to represent a
given resources state. The latter is what I was getting at above. As
far as the former is concerned, any format that facilitates linking
resources together will end up producing a graph; HAL, CJ, Siren,
etc..

[Markus Lanthaler]

On 11 Jul 2014 at 00:21, Mike Kelly wrote:

> On Thu, Jul 10, 2014 at 10:39 PM, Markus Lanthaler wrote:
>> On Thursday, July 10, 2014 2:24 PM, Mike Kelly wrote:
>>> On Wed, Jul 9, 2014 at 11:39 PM, Markus Lanthaler wrote:
>>>> Talking about JSON-LD specifically, you have the advantage that it has
>>>> a well-defined, graph-based data model.
>>>
>>> The problem for is that most people do not consider that an advantage
>>> because they are not looking for a graph-based data model. So you have
>>> a whole bunch of complexity in the format dedicated to a small subset
>>> of people that do want this, which is obviously not a good design for
>>> a general purpose media type.
>>
>> IHMO it's very weird to talk about hypermedia and "reject" graphs.
>> The whole idea of hypermedia is that you create a graph of documents/data/...
>> As soon as you introduce links you inevitably end up creating a graph. You
>> can of course try to hide that fact by flattening the graph when serializing it
>> but that doesn't change the fact.
>
> There's a difference between the graph between related resources
> (created by linking them together) and using a graph to represent a
> given resources state.

So you are saying that the relationship to other resources isn't part of the state of a resource? So if you have a resource representing a person, that resource is in the same state regardless of how it is connected to other resources (persons?). To make it more concrete, is the state of the resource /markus the same in these two examples?

a) Resource: /markus
attributes:
name: Markus Lanthaler
links:
n/a

b) Resource: /markus
attributes:
name: Markus Lanthaler
links:
relationship: knows, target: /mike (anoter resource)

I would argue no, those are clearly two different states and thus it also doesn't make that much sense IMO to strictly separate attributes from links. Links are just attributes (properties) whose value happens to be another resource (URL).

Resource: /markus
name: Markus Lanthaler
knows: /mike (another resource)

or in JSON-LD (omitting the context)

{
"@id": "/markus",
"name": "Markus Lanthaler",
"knows": { "@id": "/mike" }

}


> The latter is what I was getting at above. As far
> as the former is concerned, any format that facilitates linking
> resources together will end up producing a graph; HAL, CJ, Siren, etc..

Exactly. That's the point. You can of course separate links from other attributes to make it appear as if it would make it easier to find the links but that only changes the structural representation, not the data.


--
Markus Lanthaler
@markuslanthaler

[Jørn Wildt]

Hi Marcus

Thats a pretty good example that highlights yours/JSON-LD's way of thinking. Thanks for that. It works nicely when you think of links as relations to other resources, as in your "knows" link.

But links are also used to represent URLs for possible actions such as "edit (this)" or "add-new-issue-to-this-project". In this case it seems reasonable to separate links from data - or rather - structurally separate data from meta-data instructing the client how to work with data. Mixing the two is obviously possible, as done in Hydra, but I would say that a separated model (links/actions in one place, data in another) fits my mental model better.

/Jørn

[Markus Lanthaler]

On Friday, July 11, 2014 2:02 PM, Jørn Wildt wrote:
> Hi Marcus
>
> Thats a pretty good example that highlights yours/JSON-LD's way of thinking.
> Thanks for that. It works nicely when you think of links as relations to
> other resources, as in your "knows" link.

Aren't links always "relations to other resources"?

> But links are also used to represent URLs for possible actions such as "edit
> (this)" or "add-new-issue-to-this-project". In this case it seems reasonable

In most cases, I consider that to be an anti-pattern. I know AtomPub uses "edit" but that could just as well be replaced with something like "source" which would make the relationship clearer.

> to separate links from data - or rather - structurally separate data from
> meta-data instructing the client how to work with data. Mixing the two is
> obviously possible, as done in Hydra, but I would say that a separated model
> (links/actions in one place, data in another) fits my mental model better.

Let's stick to this example:

Resource: /markus
name: Markus Lanthaler
knows: /mike (another resource)

What is the data? What is the metadata? Where do you draw the line? Why can't "knows", despite being a typed "relation to [an]other resource" act in a similar way as "edit" or "add-new-issue-to-this-project"?

To make it even more confusing, where do you draw the line in let's say an HTML document? Would it make sense to move form "metadata" to the <head> section? Kin will have a great time to moderate the panel :-P

Cheers,
Markus


--
Markus Lanthaler
@markuslanthaler

[mca]

indicating relationships between abstract resources is just one possible use of a link. links can also be a part of explicit affordances. 

using the characters e-d-i-t to indicate a relationship is a bad idea.

however, annotating a link with the characters e-d-i-t is not an "anti-pattern", it is another use of links.

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

[Markus Lanthaler]

On Wednesday, July 16, 2014 4:45 PM, mca wrote:
> indicating relationships between abstract resources is just one
> possible use of a link. links can also be a part of explicit
> affordances.

What are "abstract resources"? What are "concrete resources"?
What are "explicit affordances"? What are "implicit affordances"?

> using the characters e-d-i-t to indicate a relationship is a bad idea.
> however, annotating a link with the characters e-d-i-t is not an
> "anti-pattern", it is another use of links.

I'm not sure I understand you correctly here Mike, but how is specifying a link's relationship type not "indicat[ing] a relationship"? Similarly, how is typing a link not a form of "annotation"?


--
Markus Lanthaler
@markuslanthaler

[mca]

<snip>

What are "abstract resources"? 

</snip>

Today's Weather

<snip>

What are "concrete resources"?

</snip>

photo of the snow storm from 2014-01-19

<snip>

how is specifying a link's relationship type not "indicat[ing] a relationship"?

</snip>

i have no idea. can't recall saying anything like that

<snip>

how is typing a link not a form of "annotation"?

</snip>

"typing" -- i assume you mean applying a "type" to a link -- is just one form of annotation. naming, categorizing, indicating ownership, adding a value of trust, marking the status, etc. are all forms of annotation.

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

--
Markus Lanthaler
@markuslanthaler

[Kin Lane]

we are going to have in Detroit. Gathering more discussion points from this thread.

Kin Lane (API Evangelist)

kin...@gmail.com

@kinlane

--

apievangelist.com

apicommons.org

apivoice.com

--

[Markus Lanthaler]

On Wednesday, July 16, 2014 5:40 PM, mca wrote:
> <snip>
> What are "abstract resources"?
> </snip>
> Today's Weather
>
> <snip>
> What are "concrete resources"?
> </snip>
> photo of the snow storm from 2014-01-19

OK, so you are talking about "information resources" [1] and non-information resources as defined by AWWW.

> <snip>
> how is specifying a link's relationship type not "indicat[ing] a
> relationship"?
> </snip>
> i have no idea. can't recall saying anything like that

I said that I generally find it an anti-pattern to use link relation types that express actions instead of, well, the type of the relationship. This was a response Jørn's:

> But links are also used to represent URLs for possible actions such as "edit
> (this)" or "add-new-issue-to-this-project". In this case it seems reasonable

so: rel="add-new-issue-to-this-project" target="/other-resource"

Your reply was quite short and thus difficult to interpret (for me, anyway):

indicating relationships between abstract resources is just one
possible use of a link. links can also be a part of explicit
affordances.

using the characters e-d-i-t to indicate a relationship is a bad
idea. however, annotating a link with the characters e-d-i-t is
not an "anti-pattern", it is another use of links.

I still struggle to make sense of the second paragraph above.


[1] http://www.w3.org/TR/webarch/#def-information-resource



--
Markus Lanthaler
@markuslanthaler

[Mike Kelly]

On Wed, Jul 16, 2014 at 5:36 PM, Markus Lanthaler
<markus.l...@gmx.net> wrote:
> On Wednesday, July 16, 2014 5:40 PM, mca wrote:
>> <snip>
>> What are "abstract resources"?
>> </snip>
>> Today's Weather
>>
>> <snip>
>> What are "concrete resources"?
>> </snip>
>> photo of the snow storm from 2014-01-19
>
> OK, so you are talking about "information resources" [1] and non-information resources as defined by AWWW.

Oh no. Please let's not go there! :)

[Markus Lanthaler]

On Wednesday, July 16, 2014 6:43 PM, Mike Kelly wrote:

> On Wed, Jul 16, 2014 at 5:36 PM, Markus Lanthaler wrote:
> > On Wednesday, July 16, 2014 5:40 PM, mca wrote:
> >> <snip>
> >> What are "abstract resources"?
> >> </snip>
> >> Today's Weather
> >>
> >> <snip>
> >> What are "concrete resources"?
> >> </snip>
> >> photo of the snow storm from 2014-01-19
> >
> > OK, so you are talking about "information resources" [1] and non-information resources as
> defined by AWWW.
>
> Oh no. Please let's not go there! :)

Yeah, that was my reaction as well when I saw Mike's mail :-)


--
Markus Lanthaler
@markuslanthaler

[mca]

<snip>

 using the characters e-d-i-t to indicate a relationship is a bad
    idea. however, annotating a link with the characters e-d-i-t is
    not an "anti-pattern", it is another use of links.

I still struggle to make sense of the second paragraph above.

</snip>

pretty sure the first sentence is not a problem since it echoes your comment to Jorn. i suspect you refer to the second sentence as the problem. the word "annotation" for me includes more then just the "rel" value. i do not find it an "anti-pattern" to indicate the use of a link with strings like "add" or "new". i *do* find it a bad idea to use the "rel" property (as defined in HTML) for this. 

is that better?

also, in my hurry to respond to your initial query, i failed to address the other questions:

<snip>

What are "explicit affordances"? 

</snip>

HTML.FORM is an explicit affordance. it spells out exactly what values to pass in a request, how to format these values, which protocol method to use, and which URL to use when sending the request.  Siren and UBER both rely heavily on explicit affordances.

<snip>

What are "implicit affordances"?

</snip>

Atom.entry@edit is an implicit affordance. it is a general promise implying  (in Atom's case) at least three protocol methods are possible (HTTP.GET, HTTP.PUT, HTTP.DELETE) and it implies that the sub elements of the entry are all valid values to pass in the request to the href value of that entry. IRL, this MAY not all be true. some methods might not be supported and some values might not be valid to pass and/or might be ignored when passed from client to server. Atom, Collection+JSON, OData, and most all CRUD-style interactions rely in implicit affordances.

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

--
Markus Lanthaler
@markuslanthaler

[Jørn Wildt]

> i do not find it an "anti-pattern" to indicate the use of a link with strings like "add" or "new". i *do* find it a bad idea to use the "rel" property (as defined in HTML) for this.

I don't disagree with this. But some media types, like for instance HAL, have no other ways to annotate links than using "rel" (and please correct me if I remember it wrong). So to express "use this link to add new issues to the issue tracker", we have to use rel="add-issue" - but, yes, "add-issue" isn't exactly what I would consider a relation to another resource - its more of a name of an affordance/action available in the current representation ... and then we get back to my original comment, where I argued that, for me, it makes sense to represent affordances separately from data - as opposed to what Hydra/JSON-LD proposes. Its not like its wrong to do it either way - its more of a personal preference.

/Jørn

--
/Jørn

[mca]

<snip>

 Its not like its wrong to do it either way - its more of a personal preference.

</snip>
+1

[Darrel Miller]

Mike,

On Wed, Jul 16, 2014 at 1:44 PM, mca <m...@amundsen.com> wrote:
> pretty sure the first sentence is not a problem since it echoes your comment
> to Jorn. i suspect you refer to the second sentence as the problem. the word
> "annotation" for me includes more then just the "rel" value. i do not find
> it an "anti-pattern" to indicate the use of a link with strings like "add"
> or "new". i *do* find it a bad idea to use the "rel" property (as defined in
> HTML) for this.

This was a light-bulb moment for me. I believe I finally see the
disconnect that has existed between our perspectives. I just chose a
different solution to the problem. I like to refer to link relation
types as simply link types because the term relation is too
constraining in that it infers something very passive. The word
"link" already communicates that there is a connection to another
resource.

The use of "rel" as the attribute to identify the link type is an
unfortunate historical artifact, but fairly insignificant.

Now I think I understand why you make the distinction between links
and forms, whereas I see it as unnecessary.

Darrel

[Kin Lane]

I know many people aren't willing to chime in, from their fence watching position....

But, I for one, learn a shit-ton, sitting on the fence watching you guys go back and forth working through this very complex stuff.

Kin Lane (API Evangelist)

kin...@gmail.com

@kinlane

--

apievangelist.com

apicommons.org

apivoice.com

--

Darrel

[Kijana Woodard]

+1

---

From: Kin Lane
Sent: ‎7/‎16/‎2014 11:46 PM
To: api-...@googlegroups.com
Subject: Re: [api-craft] Re: Anyone using RAML?

[Markus Lanthaler]

On Wednesday, July 16, 2014 7:44 PM, mca wrote:
> <snip>
> using the characters e-d-i-t to indicate a relationship is a bad
> idea. however, annotating a link with the characters e-d-i-t is
> not an "anti-pattern", it is another use of links.
> I still struggle to make sense of the second paragraph above.
> </snip>
>
> pretty sure the first sentence is not a problem since it echoes your
> comment to Jorn. i suspect you refer to the second sentence as the
> problem. the word "annotation" for me includes more then just the
> "rel" value.

OK. That was the problem. I assumed you were still talking about "rel" because my discussion with Jorn was just about that.

> i do not find it an "anti-pattern" to indicate the use of
> a link with strings like "add" or "new". i *do* find it a bad idea to
> use the "rel" property (as defined in HTML) for this.

No, of course not. It's exactly the same thing you do with the "label" in HTML all the time. Hydra actually relies quite heavily on such annotations. It allows you to bind operations such as "add" (in the form of http://schema.org/AddAction) to link relations.


> is that better?

Yep, thanks.

> also, in my hurry to respond to your initial query, i failed to address
> the other questions:
>
> <snip>
> What are "explicit affordances"?
> </snip>
>
> HTML.FORM is an explicit affordance. it spells out exactly what values
> to pass in a request, how to format these values, which protocol
> method to use, and which URL to use when sending the request. Siren
> and UBER both rely heavily on explicit affordances.
>
> <snip>
> What are "implicit affordances"?
> </snip>
>
> Atom.entry@edit is an implicit affordance. it is a general promise
> implying (in Atom's case) at least three protocol methods are
> possible (HTTP.GET, HTTP.PUT, HTTP.DELETE) and it implies that the sub
> elements of the entry are all valid values to pass in the request to
> the href value of that entry. IRL, this MAY not all be true. some
> methods might not be supported and some values might not be valid to
> pass and/or might be ignored when passed from client to server. Atom,
> Collection+JSON, OData, and most all CRUD-style interactions rely in
> implicit affordances.

Thanks... that's how I interpreted these terms but nevertheless good know for sure now that I interpreted them correctly.


--
Markus Lanthaler
@markuslanthaler

[nickdu]

I happen to be reading this thread because I was searching for RAML (which I'll post another question about) and didn't understand Mike's point:

"using the characters e-d-i-t to indicate a relationship is a bad idea.

however, annotating a link with the characters e-d-i-t is not an "anti-pattern", it is another use of links."

So if someone can explain it to me that would be great.  Examples maybe?

I can think of a couple:

HTML:

<a href="..." rel="edit">...</a>

HAL:

"_links": {
  "edit" : {"href" : "..."}
}

Are those both considered similar?

Thanks,
Nick

[nickdu]

The little bit I looked at RAML gave me the impression it was used to mock up an API for stubbing and documentation purposes.  It appeared as if it was mainly geared toward having you define all of your resource endpoints (URL's) and the methods allowed on those endpoints along with what payloads were sent returned.  Wouldn't this be considered a REST anti-pattern?

Thanks,
Nick

On Tuesday, July 8, 2014 at 12:31:18 PM UTC-6, Darrel Miller wrote:

My perspective was that people are already creating these design
formats.  Wouldn't it be cool to be able to leverage that existing
work to generate a home document.  Even if they are not the most ideal
format.

I've worked with json-home quite a bit and only being able to have one
instance of a particular link relation does make sense if you are
prepared to swallow the entire hypermedia pill but it doesn't work
well for a discovery document for URL based APIs.

Maybe I'll bump this up my to-do list a bit and maybe I'll have
something to show at api-craft or Restfest.

Darrel


On Tue, Jul 8, 2014 at 2:25 PM, mca <m...@amundsen.com> wrote:
> right - quite possible to use these description documents at runtime. IME,
> the current designs don't lend themselves well to this, but that doesn't
> mean 1) i am right or 2) we couldn't find other descirption formats that DO
> work well at runtime.
>
> i'd love to see some work in this space.
>
>
>

> 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
>
>
>

> On Tue, Jul 8, 2014 at 2:23 PM, Darrel Miller <darrel...@gmail.com>
> wrote:
>>
>> Mike,
>>

>> Do the first group have to be design time only?  I've been toying with
>> the idea of writing some media type parsers for WADL,RAML, SWAGGER et
>> al and seeing how they would work as a home document discovery page.
>> Is there a fundamental reason why they couldn't be used for runtime
>> discovery?
>>
>> Darrel
>>
>> On Mon, Jul 7, 2014 at 2:54 PM, mca <m...@amundsen.com> wrote:
>> > HAL, UBER, Cj, Siren, etc. play a different role than WADL, RAML, etc.
>> >
>> > those in the first group are runtime representation formats
>> > those in the second group are design/build time description formats
>> >
>> >
>> >
>> >

>> > 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]

I second nickdu's question.

To take one example, for the GET /widgets/{} endpoint to work HATEOAS style, it seems that the endpoint needs to be aware of all the closely related resources, e.g. GET /widgets/{}/color.

But in some environments (microservices in our case), that's not possible; the GET /widgets is produced by a very small service, which is just one of tens or hundreds that a tenant has installed.

In such an environment, each service does not have a definitive listing of all of the other installed services and their APIs - only a central authority does.

It kind of feels like HATEOAS becomes less practical in such environments, whereas RAML (or swagger or whatever - though we use RAML and find it great) is very relevant .

I hope nickdu that that is something like what you are asking and I haven't pushed the discussion off tangent.

[nickdu]

Feel free to push the question in whatever direction.  I wasn't even sure if I should be replying to this thread since it is a bit old, but I figured I would give it a try.  Not sure we're on the same page though.  I looked at RAML and it doesn't seem to fit, as far as I can tell, in a hypermedia environment.  I'm working on a hypermedia API and someone mentioned RAML so I thought I should understand it a big more.

Thanks,
Nick

[Andrew Braae]

RAML can indeed describe hypermedia APIs.

Here's an example using Collection+JSON:

#%RAML 0.8

---

title: Hello world API

/widgets:

  /{id}:

    get:

      description: get details of a specific widget

        responses:

          200:

            body:

              application/vnd.collection+json:

                schema: !include ../schemas/collectionJson.json

                example: |

                  { "collection" : 

                    {

                      "version" : "1.0",

                      "href" : "http://example.org/friends/"

                    } 

                  }

The "schema" line above is a pointer to a JSON schema document that describes what the API will give back (i.e. a Collection+JSON hypermedia document in this case). I couldn't see a schema for Collection+JSON online but there is one at http://hyperschema.org/mediatypes/collection-json which looks like it should work.

[nickdu]

I guess I didn't explain myself well enough.  What I mean by saying that RAML doesn't fit in a hypermedia environment is that, from my little bit of knowledge I have so far with hypermedia, you don't document your URL endpoints.  With a hypermedia api you only document your entry point, media types and link relations.  Therefore, if RAML is all about documenting your URL hierarchy along with the types of payloads and what verbs are allowed, I would say that's a hypermedia anti-pattern.

From http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven:

A couple of the points (there are more):

• A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]
• A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. [Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC's functional coupling].
• A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]

Thanks,
Nick

[Andrew Braae]

Even if your APIs are fully compliant with all of that goodness, you still need to *build* them.

You may find RAML a useful part of the puzzle for documenting what you are going to build.

Then if you want to try and encourage developers to build clients that use your hypermedia controls, don't publicly release your RAML.

[Thomas Lörcher]

Hello,

I absolutely agree to the points of nickdu.

In my opinion those description formats (RAML, YAML,...) circumvent the points HATEOAS is all about.

They lead to a hard coupling of servers and clients. You aren't able to extend the API of the server, to adapt it. You need to version it (compare the versioning rant of Roy Fielding)

They circumvent the self-description constraint. 

We need to intense our efforts in defining and expand our common understanding of semantics (like the guys doing in ALPS, microformats, etc.) instead of intensing the work in those 

hard-coupling description languages.

Even if your APIs are fully compliant with all of that goodness, you still need to *build* them.

You may find RAML a useful part of the puzzle for documenting what you are going to build.

Then if you want to try and encourage developers to build clients that use your hypermedia controls, don't publicly release your RAML.

As I observe those formats aren't used as internally documentation but rather as external contract. That's actually horrible!

Regards

[darrel...@gmail.com]

Nick,

Many people building APIs find an API description language that list the available resources a useful approach to describing/documenting a HTTP API.

However, documentation for a hypermedia driven API requires a different set of artifacts.

It is two different approaches with do different sets of pros and cons.

Darrel

Sent from Surface

[nickdu]

Darrel,

Not sure what you mean.  Do you mean that RAML is for documenting a Web API, e.g. not a hypermedia API?  And a hypermedia API needs a different kind of documentation, like media type and link relations?  If so, then are you saying I'm correct in stating that RAML, at least as far as the examples I have seen, is not appropriate for documenting a hypermedia API?

Thanks,
Nick

[Oliver Wolf]

Nick,

RAML is designed for providing a client with a-priori knowledge about a service (potentially by generating parts of the client implementation from the description). This is a very different approach from hypermedia which is more about what I would refer to as situational awareness, i.e. the client needs to be able to figure out what to do based on hypermedia controls included with the response messages received from the service. It would certainly be possible to describe a hypermedia API in RAML to some extent, but it’s pretty pointless IMHO as the client cannot assume that the model and the actions haven’t changed since the RAML description was published. Likewise, a dynamically generated RAML document (and a client generic enough to interpret it at runtime) could serve as a “poor man’s” replacement for hypermedia, but doesn’t really add any value over real hypermedia controls. 

So the bottomline is: I think you’re correct in stating that RAML is not appropriate for documenting a hypermedia API. Hypermedia APIs should be documented in terms of describing the semantics of link relation types, not in terms of describing the resource structure.

Oliver

[darrel...@gmail.com]

Nick,

That’s pretty much what I am saying… at least that is  my opinion.

Darrel

[Mark Derricutt]

On 17 Mar 2015, at 4:12, Oliver Wolf wrote:

> So the bottomline is: I think you’re correct in stating that RAML is not appropriate for documenting a hypermedia API. Hypermedia APIs should be documented in terms of describing the semantics of link relation types, not in terms of describing the resource structure.

It'd be really good is there WAS a a raml/swagger like framework FOR documenting hypermedia based APIs - in a consistent manner.

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

[darrel...@gmail.com]

Mark,

I agree. However, I’ve yet to see an API description language that even tries to address the concept of documenting a link relation.  On the surface, it would seem fairly straightforward.  Identify the URLs of entry point resources.  Document link relation types in pretty much the same way that API description languages currently document resources.  i.e. Identify the HTTP methods supported, the parameters used in URI templates and the media types that are accepted and returned.  Then list the media types/profiles/schemas supported by the API.  Also would be nice to register a well-known URL to discover the description document.

Darrel

Sent from Surface

[Jørn Wildt]

What Darrel describes is pretty much how we have done it (using Word, not some kind of smart DSL): some introduction on the general data model, concepts and authentication methods, then a description of all the possible kinds of resources available (without their URL templates) followed by a description of all the relationship types.

The root description document (which we call the service index(*)) is the only public documented URL ... and even that is not in the docs as the system is installed on-premise at the customers so we never know what URLs we end up with :-)

It should be fairly simple to generalize that into some sort of DSL to generate HTML/PDF/other from - but I am having a hard time seeing what other benefits it could yield. Ideas anyone? If the URL templates were included in the DSL (but not in the generated docs) then it might be possible to create some kind of mock-up from it. But it wouldn't be much different from RAML/Swagger/what-ever - except that it also describes link relation types, both the complete set as well as the expected relations available on each resource type.

/Jørn

(*) That might be slightly misleading for a resource oriented system.

[Jonathan Robie]

This sounds a lot like the latest version of RADL, which we will be posting to github in the next few weeks.  (The currently available version takes some steps in that direction, but does not go as far as the internal version that we will post soon.)

Jonathan

[Evan Cordell]

It should be fairly simple to generalize that into some sort of DSL to generate HTML/PDF/other from - but I am having a hard time seeing what other benefits it could yield. Ideas anyone?

Couldn't this be an effective way to create an automated tests of the service? Regardless of hypermedia, there is always a contract in an API that needs verification. API Blueprint has some good tools in that area, but there's nothing especially hypermedia-aware about it.

[Rémon Sinnema]

We have a new version of RADL up on GitHub:
https://github.com/restful-api-description-language/RADL
Feedback is very welcome.

[Mike Kelly]

On Wed, Mar 18, 2015 at 1:08 AM, Mark Derricutt <ma...@talios.com> wrote:

On 17 Mar 2015, at 4:12, Oliver Wolf wrote:

> So the bottomline is: I think you’re correct in stating that RAML is not appropriate for documenting a hypermedia API. Hypermedia APIs should be documented in terms of describing the semantics of link relation types, not in terms of describing the resource structure.

It'd be really good is there WAS a a raml/swagger like framework FOR documenting hypermedia based APIs - in a consistent manner.

I usually just create a markdown styleguide/template for documenting link relations, that's usually enough and avoids unnecessary constraint. The main point of documentation should be to convey the relevant information clearly and succinctly. Structural consistency of the documentation can play a part in that but consistency shouldn't necessarily be a goal in and of itself.

Cheers,

M