Subject: [apps-discuss] Teaching a Bot How to Create a Resource

From: Joe Job <[email-masked]>
Date: Thu, 22 May 2014 14:08:42 +0100

Forgive me if this question is inappropriate for this list, but I've been
reading standards documents for days trying to answer this question to no
avail.

Consider an automated API client that wants to create a resource knowing:

* The API's "billboard URL"
* That to create a resource without knowing its URL you POST
* The resource's media type.

How does the client discover the URL to POST to? The principles of Web
Linking don't appear to be much help here for two reasons:

* Links implicitly describe a representation received with GET. The URL to
which a new representation can be POSTed is unlikely to respond to a GET
with the same media type it creates.
* There doesn't seem to be a link relation that captures the idea of a
target URL that creates a resource of a different type than the context
URL. `create-form` is registered as "The target IRI points to a resource
where a submission form can be obtained.", but RFC6861 defines that it
"indicates a target resource that represents a form that can be used to
append a new member to the link context." (
http://tools.ietf.org/html/rfc6861#section-3.1) The latter definition
implies the context is a collection and the form will create a member of
that collection, whereas in this example the client does not want to create
a member of the billboard URL's collection---nor is there such a
collection---but a member of a collection linked from the billboard URL. If
we use IANA's description, and gloss over what a generic form is, then the
billboard URL could link to its sub-resources with this relation. In this
case, the client only needs to distinguish between links with this relation.

With `Accept-Post`, the client could proceed by visiting each link with the
`create-form` relation, then comparing its desired media type to those
advertised by the resource.

However, in general the media type alone isn't sufficient to describe a
resource, hence the `type`, `profile`, `describedby`, and similar
relations. In my case I'll probably use JSON-LD as the media type, and a
schema from schema.org to describe the resource. Then the client needs to
know only an opaque schema identifier and the media type. This fits
perfectly with the example in RFC6903 of rel `type`, but how do I declare a
resource that can mint instances of this media type and rel type
combination? A resource describes itself as having these properties is
implicitly describing its GETable representation, or "form". `Accept-Post`
doesn't seem to help here because its granularity is the media type. The
closest I can come is having the client crawl the API until it finds a
resource with the right media type and rel `type`, follow a `create-form`
link from there, then POST to that URL. I'm hoping there's a more elegant
solution.

-Ben

---

From: Erik Wilde <[email-masked]>
Date: Thu, 22 May 2014 09:45:59 -0700

hello joe.

On 2014-05-22, 6:08, Joe Job wrote:
> * Links implicitly describe a representation received with GET. The URL
> to which a new representation can be POSTed is unlikely to respond to a
> GET with the same media type it creates.

maybe of interest to you:

Accept-Patch: http://tools.ietf.org/html/rfc5789#section-3.1

Accept-Post: http://tools.ietf.org/html/draft-wilde-accept-post-02

cheers,

dret.

-- 
erik wilde | mailto:[email-masked]  -  tel:+1-510-2061079 |
            | UC Berkeley  -  School of Information (ISchool) |
            | http://dret.net/netdret http://twitter.com/dret |

---

From: "Markus Lanthaler" <[email-masked]>
Date: Thu, 22 May 2014 19:27:17 +0200

> Linking don't appear to be much help here for two reasons:
[...]
> 
> However, in general the media type alone isn't sufficient to describe
> a resource, hence the `type`, `profile`, `describedby`, and similar
> relations. In my case I'll probably use JSON-LD as the media type, and
> a schema from schema.org to describe the resource. Then the client
> needs to know only an opaque schema identifier and the media type.
> This fits perfectly with the example in RFC6903 of rel `type`, but how
> do I declare a resource that can mint instances of this media type and
> rel type combination? 

You should probably have a look at Hydra [1] (there's a little demo at [2]). If you find it interesting, you should join the Hydra W3C Community Group [3] which is working on its further development. There's also a mailing list dedicated to Hydra at W3C [4].

HTH,
Markus

[1] http://bit.ly/HydraED
[2] http://bit.ly/hydra-api-demo
[3] http://bit.ly/HydraCG
[4] [email-masked]

--
Markus Lanthaler
@markuslanthaler

---

From: Mark Baker <[email-masked]>
Date: Thu, 22 May 2014 14:16:31 -0400

> * That to create a resource without knowing its URL you POST

The thing is, if you're using POST then your client will only know
whether a resource was created if it receives a 201 response.
Otherwise it's just data into the ether, per POST's rather opaque
semantics.

If your client really needs to explicitly request the creation of a
resource, you need an HTTP method for that. Have you tried working out
a PUT based solution?