Default media type

[RaySinnema]

If an API uses a single media type for most of its messages, it's quite annoying that it must repeat that over and over again.

Currently, the schema allows this:

<method name="GET">
  <response>
    <representations/>
  </response>
</method>

We could decide that that means it returns the only defined media type, but it doesn't look very elegant...

[gentlewind]

It's helpful to return the only defined media type for such a case.

[RaySinnema]

I'm not sure I understand. Do you mean the following?

<method name="GET">
  <response>
    <representations>
      <representation media-type="application/ld+json"/>
    </representations>
  </response>
</method>

All methods of all resources will look like that. Simply repeating something over and over again isn't adding any information, only noise.

[gentlewind]

Sorry for the confusion! I meant to say I agree that it is helpful to ignore the only defined media type.

[RaySinnema]

• RAML has a default media type.
• Swagger has a default as well, but splits it up into consumes and produces

[jonathanrobie]

This is a common use case, I agree that this is a good idea, and I will add it to the schema.

[jonathanrobie]

There are at least three ways we could do this.

1. If contains only one media type, it is automatically treated as the default media type. This is simpler in the very common case where only one media type is ever used, and requires no change to the schema (but does require changes to the stylesheet).
2. Add a default attribute: , where the value is the name of a media type. This is simpler in the case where there are multiple media types but most messages use a given media type.
3. Add a default attribute, but require it only if more than one media type is present.

Which do you prefer?

[RaySinnema]

I like 3 best.

I take it the proposed default attribute will be on the media-types element?

[jonathanrobie]

Yes, the default attribute will be on the media-types element.

[RaySinnema]

We could go with a default attribute on <media-type> and if it's not set then treat the first media type as default. That looks nice for when there is only one media type, but also works well for when there are several.

[gentlewind]

+1

[jonathanrobie]

I don't like treating the first media type as default. The meaning should not depend on the order.

I think I would like to see the default media type in the media-types element:

The default attribute is optional, if omitted there is no default media type. We may want to have a small number of well-known media types for which a 'media-type' element is not required, e.g. 'text/html', 'application/json'.

On Wed, Aug 12, 2015 at 3:29 AM, Rémon (Ray) Sinnema < notifications@github.com> wrote:

We could go with a default attribute on and if it's not set then treat the first media type as default. That looks nice for the case there is only one media type, but also works well for when there are several.

— Reply to this email directly or view it on GitHub https://github.com/restful-api-description-language/RADL/issues/14#issuecomment-130200178 .

[RaySinnema]

+1

[gentlewind]

+1