Defining PUT operation for new object creation

[AlexMaskovyak]

Hello,

I'm defining a hypermedia API and am experimenting with Siren. I notice that PUT operations on existing entities can be handled easily.

As an example, I can define an update action for a resource with id=55 like so:
{
'name': 'update-existing',
'method': 'PUT',
'href': '/resource/55',
'fields': [ { 'name': 'field1', 'type': 'text' } ]
}

However, there doesn't appear to be a way to define PUT operations for the creation of new entities. When using a PUT in this way it's typical to specify the URI of the new resource. How would I specify that someone can create a resource with an arbitrary id when that id is specified in the href itself and is not a posted parameter?

The mechanism would have to be similar to this:
{
'name': 'create-new-with-id',
'method': 'PUT',
'href': '/resource/{id}',
'fields': [ { 'name': 'field1', 'type': 'text' } ]
}

[smrgeoinfo]

does Siren let you use URI templates?

Stephen M Richard
Arizona Geological Survey
416 W. Congress #100
Tucson, AZ
AZGS: 520-770-3500
Office: 520-209-4127
FAX: 520-770-3505

[apsoto]

@AlexMaskovyak a typical REST create is a POST to /resource. However, if URI template is what you want to use, I would say it's a proper use of it.

@smrazgs IMO, there's nothing that says you can't.

[AlexMaskovyak]

When a client is relying upon the service to assign an id (surrogate keys), then absolutely, a POST to /resource is typical. In cases where the client is responsible or able to assign the id (natural keys or keys that are generated by a separate service), then a PUT to /resource/{id} is common.

[kevinswiber]

@AlexMaskovyak @smrazgs Siren doesn't explicitly support URI Templates. If you used URI templates in your API and included that piece of information in your docs, that shouldn't be a problem.

The way I model APIs, I often create resources via an Aggregate Root, to borrow a term from Domain-Driven Design. I make the creation of new resources the responsibility of a parent resource. This has tons of benefits for me on the API server implementation side (just by the way I structure my own models). Therefore, creating with a PUT is not something I've done in a Siren API yet.

There's nothing wrong with it, though! If you go through with it, I wouldn't mind hearing about your experience using URI Templates with Siren.

Cheers.

[AlexMaskovyak]

Out-of-band documentation defeats some of the point of hypermedia. Self-discovery and programmatic client generation rely upon response objects that have sufficient expressiveness to capture functional requirements.

[kevinswiber]

@AlexMaskovyak That statement means more to theorists than practitioners. I find myself spanning both roles frequently. In today's world, there is always out-of-band documentation. What's the root URL? How do I handle authentication/authorization? What are the deeper business semantics around the exposed resources? What do the custom link relations map to in the business domain?

If you want to shift the issue to discussing URI Template support in Siren, I'm certainly open to that discussion! I don't use them, personally, which is likely the only reason they're not mentioned in the Siren specification.

If you want to take a look at hypermedia types that explicitly couple to URI Templates, here are a few:

• HAL: http://tools.ietf.org/html/draft-kelly-json-hal-06
• Uber: https://github.com/mamund/media-types/blob/master/uber-hypermedia.asciidoc
• Hydra: http://www.hydra-cg.com/spec/latest/core/

[ericelliott]

I think it's a good idea to support URI templates.

Also, if you're letting clients generate IDs, be very careful. See cuid.

[AlexMaskovyak]

Despite it being off-spec, I am using URI templates to define the names and locations for injecting path parameter values. URI parameter typing can be defined in the fields area where query/post parameters are defined, however, one will need to be mindful of name collisions. I will note that URI templates in my client implementation could also be used for defining query parameters. I'm currently ambivalent about that ability but see that as possibly causing confusion in the future.