-
Notifications
You must be signed in to change notification settings - Fork 0
Openwrap publishing protocol
The OpenWrap publishing protocol is a specialization of the HTTP 1.1 application as defined in http://www.ietf.org/rfc/rfc2616.txt.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14, [RFC2119], as scoped to those conformance targets.
The OpenWrap Publishing Protocol contains varying amounts of functionality, hereby called Features, that an application MAY implement.
As each of those features is optional, a user-agent MUST automatically detect which of those features is available. This specification makes no attempt at defining when a user-agent can operate that detection.
Any client not using automatic detection will not be considered compliant with this specification.
The available features of the OpenWrap Publishing Protocol are:
- Package Listing
- Incremental package listing
- Package publishing
This specification does not imply the use of a specific media type, be it for the package format itself or for the package lists.
Resources exposed over the OpenWrap Publishing Protocol CAN contain links, as defined in http://tools.ietf.org/html/rfc5988, to entrypoint URIs a user agent (such as the OpenWrap Shell) may use to get access to a specific feature of the protocol.
To enable hosting of multiple applications implementing the OpenWrap Publishing Protocol on the same server, a user-agent will issue a request to a bookmark URI and attempt to discover links in the provided response.
If the response does not contain links to features, the user-agent MUST attempt a similar request by dereferencing the original URI, minus the last segment.
For example, given a bookmark URI of http://example.com/apps/packages, requests MUST be issued to the following URIs.
In the case where dereferencing a URI leads to a redirect (a response status code in the 300 range),
The full index is a resource containing a reference to all packages available on a system.
The resource MUST have a representation available using the OpenWrap Packages media-type (as specified below), and MAY have additional representations.
Any resource available in an OpenWrap Publishing Protocol compliant application MUST link to the full index resource if the full index feature is available.
The link to the full-index resource has a relationship of "index".
For example, issuing a HEAD request on a resource would trigger the following exchange.
Client Server
| 1.) HEAD / |
|----------------------------------------------------------------->|
| |
| 2.) 200 OK |
| Content-Length: 0 |
| Link: <http://wraps.openwrap.org/index/full>; rel="index" |
|<-----------------------------------------------------------------|
| |
The incremental package listing allows a server to efficiently serve the latest changes to a package list to user agents.
If the application supports the incremental package listing feature, resources available in the application MUST be linked to a recently changed list of packages, hereby named the recent changes resource.
The link relationship to the recent changes document uses the "current" relationship.
For example, given a full-index resource present at http://wraps.openwrap.org/index/full, the recent changes resource will be linked using the "current" relationship type, as follow:
Client Server
| 1.) HEAD /index/full |
|------------------------------------------------------------------->|
| |
| 2.) 200 OK |
| Content-Length: 0 |
| Link: <http://wraps.openwrap.org/index/recent>; rel="current" |
|<-------------------------------------------------------------------|
| |
The recent list can contain as many or as few recent changes as needed.
In order for a user agent to retrieve updates that predate the oldest entry in the recent changes resource, that resource may be linked to a previous archived resource.
Any resource containing a list of package entries may link to the previous resource containing entries that pre-date the ones it contains and that have been archived.
The relationship used to link to that resource is "prev-archive" .
The recent changes resource, and the full index resource if implemented, MUST contain a link to a prev-archive resource. Note that this resource may not be created yet, and dereferencing its URI may result in a 404. This allows servers to pre-generate a URI before there is anything to archive.
Archived entries, if available, MUST NOT change once they have been published.
A user agent that wishes to synchronize a list of packages will start by trying to locate the full index resource.
If the full index resource is available, the user agent will retrieve the document by dereferencing the discovered URI.
If the full index contains a link with a current relationship, it MUST also contain a link with a prev-archive pointing to the last archived list available that is wholly contained by the full index.
A user agent can then retrieve the current list to get the latest updated packages. If the client sees a link with relationship of prev-archive it has not processed yet, it can follow that link to get more updated packages. The process is repeated until a link with relationship of prev-archive is found that matches the last processed archived feed, in this scenario the one linked to by the full list resource.
An application supporting the publishing of packages exposes the feature by linking its resources to a resource with a relationship of "http://rels.openwrap.org/owapp/publish", hereby referred to as the publisher resource.
The publisher resource MUST support the POST method with a package provided as the request entity body.
To allow for authentication and authorization to be applied by a server, a user-agent SHOULD issue the POST request using the Expect: 100 http header, as specified in http://tools.ietf.org/html/rfc2616#section-8.2.3.
Additional target attributes MAY be provided together with the link.
The accept attribute contains a comma-separated list of media types, optionally followed by a quality attribute ("q") separated by a semicolon, with the same semantics as the Accept header defined in http://tools.ietf.org/html/rfc2616#section-14.1. If the value contains comas or semicolons, the value must be quoted.
The following are valid values. Link: http://wraps.openwrap.org/publisher; rel=http://rels.openwrap.org/owapp/publish; accept=application/vns.openwrap.package
Link: <http://wraps.openwrap.org/publisher>;
rel=http://rels.openwrap.org/owapp/publish;
accept="application/vnd.openwrap.package; flavour=bin+pdb; q=1.0, application/oebps-package+xml;q=0.5"
The presence of the accept attribute is non-normative, and a user-agent MUST NOT assume that it represents the whole list of accepted media types. The values in the attribute are only to be used as hints by a user-agent.
A successful publish MUST result in a 201 response, and MAY include a Location: header specifying the location of the uploaded package.
An application may decide that the package cannot be published, either because the user does not have the correct rights, or because a package already exists. In those situation, a server MUST return a 403 Forbidden response status, and SHOULD include a response entity containing a description of the reason for the refusal to process the request.
Other status codes in the 200 and 400 ranges are not defined by this specification.
- Hypertext Transfer Protocol -- HTTP/1.1 - RFC 2616 - http://tools.ietf.org/html/rfc2616
- Web Linking - RFC 5988 - http://tools.ietf.org/html/rfc5988
- Feed Paging and Archiving - RFC 5005 - http://tools.ietf.org/html/rfc5005