The Apache Maven Repository REST Applications and Protocol Bindings
draft-apache-maven-repository-rest-applications-01

Abstract

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.

Status of this Memo

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.

1. TODOs and Notes
2. Introduction
2.1. Goals:
2.2. Implementation goals
2.3. Areas explicitly not covered
2.4. Deployment scenarios
3. Specification
3.1. Media Types
3.2. Operations
3.3. Uploading Artifacts
3.4. Downloading Artifacts
3.4.1. Download a single artifact
3.4.2. Download a set of artifacts
3.5. Searching
4. Protocol Bindings
4.1. Response Bindings
5. Security Aspects
5.1. Authentication and Authorization
6. User-Agent Considerations
7. HTTP Binding
8. Appendix: Words and Definitions
9. Security Considerations
10. IANA Considerations
10.1. Link Relation: http://maven.apache.org/rel/pom
10.2. Link Relation: http://maven.apache.org/rel/md5
10.3. Link Relation: http://maven.apache.org/rel/sha1
10.4. Media Type: text/vnd.maven.pom
10.5. Media Type: text/vnd.maven.md5
10.6. Media Type: text/vnd.maven.sha1
11. Acknowledgments
12. IANA Considerations
13. Security Considerations
14. References
14.1. Normative References
14.2. Informative References
Author's Address

1. TODOs and Notes

Is it useful to register "Maven Coordinate" HTTP header? Maven-Coordinate: groupId=com.example, artifactId=example, type=jar, classifiers=awesome, version=1.2.3
Promising media types and link relations:
- "describedby" link relation - a link from an artifact to its POM
- "edit" link relation describing an external form of editing. useful if we don't want to include all the edit controls inside feeds. Reduces bandwidth and latency
- atom and collection+JSON seem like nice formats for manipulating lists of artifacts.
- metalink looks like a nice way to include
  - There are both a standalone XML format and a HTTP binding that can be used. It might be feasible to include metalink inside atom and possibly metalink inside collection+JSON

2. Introduction

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]. View Source

2.1. Goals:

Any user agent should be able to rely on caching information given by the repository. No explicit caching should be necessary by the application using a user agent for a Maven repository. In other words, no ~/.m2/repository or ~/.ivy2.
It should be possible to use standard HTTP intermediates without interfering. This is required to cover several use cases:
- Teams inside a corporation might be far away from a central repository and/or have a slow link. A local cache will be able to answer their queries faster.
- A central repository might get a very high number of requests. A cache next to the back-end application will help scale the repository as it will take load of the back-end application.
The applications should be easy to use with current command line clients.

2.2. Implementation goals

There shouldn't be any need to invent lots of media types or link relations. The operations should be able to fit within existing hyper medias.

2.3. Areas explicitly not covered

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.

2.4. Deployment scenarios

Standalone repository - similar to nexus, Artifactory etc
Mirror application
- rsync-ed copy of another repository with extra meta data
- Partial mirror of another repository
Security proxy of another mirror
- can require authentication

3. Specification

3.1. Media Types

TODO: Find a reference to @mamund's "you should always design a new media type (but not format)".

3.2. Operations

Upload artifact
- Single files
- Single artifact + signatures and checksums?
Upload set of artifacts - zipped? multipart?
Move/copy artifacts between repositories
- promote artifacts from staging to test to production
- copy from internal repository to external repository
Sign artifact
Lists of recently uploaded/changed files
Download bigger chunks of an archive
- Download entire applications with one GET
- Download the latest changes from a repository
Searching
- Search for group id, artifact id, by type, by classifier, signed by
- Search content of artifacts - find all jars with class foo.Bar, all classes that implement javax.servlet.Servlet

3.3. Uploading Artifacts

It should be possible to:

Upload a single artifact
Upload a bundle of artifacts in a single upload
Attach signatures to an artifact

3.4. Downloading Artifacts

It should be possible to

3.4.1. Download a single artifact

3.4.2. Download a set of artifacts

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.

3.5. Searching

Servers SHOULD implement conditional controls so it's possible to poll the server regularly.

4. Protocol Bindings

4.1. Response Bindings

5. Security Aspects

5.1. Authentication and Authorization

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.

6. User-Agent Considerations

A user-agent should include information on how stale data it allows. This make it possible for caches to in

A user agent must always check that it got the data it required after receiving a response.

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.

7. HTTP Binding

Explain what extra headers can be given with each response for artifacts:

Checksums: MD5, SHA-1
Cryptographic signatures, either complete signatures or links to signatures
File size

8. Appendix: Words and Definitions

Maven Repository

A Maven Repository contain a set of artifacts. Each artifact is identified by a:

group id
artifact id
version
type
classifier - this is optional

See Also (The Maven site at apache)[http://maven.apache.org]

9. Security Considerations

10. IANA Considerations

TODO: Move media types here or this section down.
TODO: Check if there are other checksum relations that are as useful. It might be possible to reuse something here. Would be make sense to register a "text/checksum" type and assume that all clients can use content negotiation to find it? Should it be registered at all, or should it be assumed that the application always can implement RFC3230?

10.1. Link Relation: http://maven.apache.org/rel/pom

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.

10.2. Link Relation: http://maven.apache.org/rel/md5

10.3. Link Relation: http://maven.apache.org/rel/sha1

10.4. Media Type: text/vnd.maven.pom

10.5. Media Type: text/vnd.maven.md5

10.6. Media Type: text/vnd.maven.sha1

11. Acknowledgments

12. IANA Considerations

13. Security Considerations

14. References

14.1. Normative References

[RFC1864]	Myers, J. and M. Rose, "The Content-MD5 Header Field", RFC 1864, October 1995.
[RFC2119]	Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616]	Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC3230]	Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", RFC 3230, January 2002.
[RFC4287]	Nottingham, M. and R. Sayre, "The Atom Syndication Format", RFC 4287, December 2005.
[RFC4627]	Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC5854]	Bryan, A., Tsujikawa, T., McNab, N. and P. Poeml, "The Metalink Download Description Format", RFC 5854, June 2010.
[RFC6249]	Bryan, A., McNab, N., Tsujikawa, T., Poeml, P. and H. Nordstrom, "Metalink/HTTP: Mirrors and Hashes", RFC 6249, June 2011.

14.2. Informative References

[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.

Author's Address

Trygve Arktekk NO Phone: +47 926 99 070 EMail: trygvis@inamo.no