| Network Working Group | TL Laugstol |
| Internet-Draft | Arktekk |
| Expires: May 14, 2012 | November 2011 |
The Apache Maven Repository REST Applications and Protocol Bindings
draft-apache-maven-repository-rest-applications-01
This document describe an architecture for a set of applications can access Maven repositories. The architecture is defined within the constrains of REST. Each application describe a useful interaction between a server and a client and the architecture ties the applications together with common traits and constraints.
This document is an Internet-Draft and is NOT offered inaccordance with Section 10 of RFC 2026, and the author does not provide the IETF with any rights other than to publish as an Internet-Draft.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on May 14, 2012.
Should this whole thing be turned into a more generic "artifact repository". This would make it easier to support repositories for particular scala versions (so you won't have to highjack Maven's semantics with artifactId = realArtifactId + "_" + scalaVersion.
It would also be easier to add support for extra attributes like "build number", "jenkins build", "henkins job name" and "build timestamp".
How should these attributes be describes? One possible option is a "profile" per repository that describe the possible attributs. You'd get a "maven profile", "jenkins profile"/"ci profile" etc. Does the values imply special values? Could a "maven profile" specify that 'if you upload an artifact with build-number set to next the server will pick the next available build number'. Having the server to a lot of work is in the vain of making it easier to implement user agents, but at the same time you're specifying semantics that are to be valid for all times.
I guess it all comes down to how much should be put in as attachments to an artifact vs how much should these applications be involved.
If this is to be done specify bindings for Maven Artifacts, Scala Artifacts (basically Maven Artifacts + scala version), Sbt Plugin Artifacts, Debian packages, OpenCSW packages.
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 RFC 2119 [RFC2119].
This specification will not apply to the existing static Maven repositories.That would be impossible within reason and there are already enough tools to support that kind of repositories. However, it inside this specification to be able to create an application that support the operations while still points to a static repository for providing the actual artifacts.
TODO: Find a reference to @mamund's "you should always design a new media type (but not format)".
It should be possible to:
Steps to download a single artifact with a specific version:
Download the start resource and find a form named download-artifact.
Artifacts can be identified either through an artifact URN or a full set of coordinates. To use the URN mechanism fill out the urn field, to use the coordinate version fill out the fields named groupId, artifactId, version, type and classifier. The classifier field is optional. These fields MUST be present in the form.
TODO: Some possible optional controls: filename.
Submit the form. The server MAY return a single artifact, see Section 5.4.1.
The set might be a search, or just a list of artifacts. The server is free to choose to send a container format with all the files in it, or just an URL list with pointers.
Servers SHOULD implement conditional controls so it's possible to poll the server regularly.
TODO: specify how to query for only changes after a certain timestamp.
Authentication and authorization is generally not specified by this specification as it is assumed that the transport mechanisms will specify the different options for authentication.
A user-agent should include information on how stale data it allows when requesting artifacts. This make it possible for caches to include caching information in the return response that intermediates also will use.
TODO: Are there any standard ways in HTTP to do this?
A user agent must always check that it got the data it required after receiving a response. This means checking response code and content type in particular.
User agents should implement a way to force an updated answer from the server, similar to what contemporary web browser to when the user explicitly reloads a page. For HTTP this includes sending a max-age=0 when requesting the data. This spesification specifically allows servers to send 410 Gone (See HTTP/1.1, Section 10.4.11) for artifacts that it knows won't ever come. A case where this is useful is if an artifact is uploaded and it's sources and javadoc artifacts are not there. A user agent MUST use any caching info given with the response. By specification the response can be cached forever.
TODO: Add info on 305 Use Proxy, section 10.3.6 of HTTP/1.1.
If a response include many links with the same relation and content type, it should can try all links to get the data. This makes it possible for a server to include pointers to many servers that can respond to the same request. A user agent should try to stick to the same host (as defined by the URI) for the following requests.
TODO: It this mainly covered by metalink?
When the user agent is downloading a form with unknown controls they MUST be sent back to the server with any value specified.
HTTP responses SHOULD include a Content-Disposition header with Disposition Type set to attachment to indicates that the artifact shouldn't be processed according to its media type. See also Content-Disposition in HTTP [RFC6266]. Those implementations that use generic HTTP servers to serve the artifacts might not include the header as it could be shared between many applications.
When the server replies with a set of artifacts it MAY send one of the following responses. If the response is one of the specified responses, it MUST follow this specification.
See the text/uri-list specification [RFC2483].
TODO: Specify application/atom+xml, text/collection+json responses too.
Explain what extra headers can be given with each response for artifacts:
See Also (The Maven site at apache)[http://maven.apache.org]
A pointer to a Maven POM file.
TODO: Should probably not be here, a link with rel=describedby, contentType=text/vnd.maven.pom is probably fine.
Should it be urn:maven:artifact, urn:maven or urn:artifact-repository.
Use template in http://tools.ietf.org/html/rfc3406#appendix-A
Creating an informal registration seems the right way to do as long as this document doesn't become an RFC.
URN notes:
| [RFC1321] | Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, April 1992. |
| [RFC3174] | Eastlake, D. and P. Jones, "US Secure Hash Algorithm 1 (SHA1)", RFC 3174, September 2001. |
| [RFC3406] | Daigle, L., van Gulik, D., Iannella, R. and P. Faltstrom, "Uniform Resource Names (URN) Namespace Definition Mechanisms", BCP 66, RFC 3406, October 2002. |