draft-laugstol-apache-maven-repository-rest-applications-00.txt		draft-laugstol-apache-maven-repository-rest-applications-01.txt
	skipping to change at page 1, line 43		skipping to change at page 1, line 43
	This Internet-Draft will expire on May 14, 2012.		This Internet-Draft will expire on May 14, 2012.
	Table of Contents		Table of Contents
	1. TODOs and Notes . . . . . . . . . . . . . . . . . . . . . . . 2		1. TODOs and Notes . . . . . . . . . . . . . . . . . . . . . . . 2
	2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2		2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
	2.1. Goals: . . . . . . . . . . . . . . . . . . . . . . . . . . 2		2.1. Goals: . . . . . . . . . . . . . . . . . . . . . . . . . . 2
	2.2. Implementation goals . . . . . . . . . . . . . . . . . . . 3		2.2. Implementation goals . . . . . . . . . . . . . . . . . . . 3
	2.3. Areas explicitly not covered . . . . . . . . . . . . . . . 3		2.3. Areas explicitly not covered . . . . . . . . . . . . . . . 3
	3. Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 3		2.4. Deployment scenarios . . . . . . . . . . . . . . . . . . . 3
	4. Deployment scenarios . . . . . . . . . . . . . . . . . . . . . 4		3. Specification . . . . . . . . . . . . . . . . . . . . . . . . 3
	5. Standalone repository - similar to nexus, artifactory etc . 4		3.1. Media Types . . . . . . . . . . . . . . . . . . . . . . . 3
	6. Mirror application . . . . . . . . . . . . . . . . . . . . . . 4		3.2. Operations . . . . . . . . . . . . . . . . . . . . . . . . 4
	6.1. rsync-ed copy of another repository with extra metadata 4		3.3. Uploading Artifacts . . . . . . . . . . . . . . . . . . . 4
	6.2. Partial mirror of another repository . . . . . . . . . . . 4		3.4. Downloading Artifacts . . . . . . . . . . . . . . . . . . 4
	7. Security proxy of another mirror . . . . . . . . . . . . . . . 4		3.4.1. Download a single artifact . . . . . . . . . . . . . . 4
	7.1. can require authentication . . . . . . . . . . . . . . . . 4		3.4.2. Download a set of artifacts . . . . . . . . . . . . . 5
	8. Security Aspects . . . . . . . . . . . . . . . . . . . . . . . 4		3.5. Searching . . . . . . . . . . . . . . . . . . . . . . . . 5
	8.1. Authentication and Authorization . . . . . . . . . . . . . 4		4. Protocol Bindings . . . . . . . . . . . . . . . . . . . . . . 5
	9. User-Agent Considerations . . . . . . . . . . . . . . . . . . 4		4.1. Response Bindings . . . . . . . . . . . . . . . . . . . . 5
	10. HTTP Binding . . . . . . . . . . . . . . . . . . . . . . . . . 4		5. Security Aspects . . . . . . . . . . . . . . . . . . . . . . . 5
	11. Appendix: Words and Definitions . . . . . . . . . . . . . . . 5		5.1. Authentication and Authorization . . . . . . . . . . . . . 5
	12. Security Considerations . . . . . . . . . . . . . . . . . . . 5		6. User-Agent Considerations . . . . . . . . . . . . . . . . . . 5
	13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5		7. HTTP Binding . . . . . . . . . . . . . . . . . . . . . . . . . 5
	13.1. Link Relation: http://maven.apache.org/rel/pom . . . . . 5		8. Appendix: Words and Definitions . . . . . . . . . . . . . . . 5
	13.2. Link Relation: http://maven.apache.org/rel/md5 . . . . . 5		9. Security Considerations . . . . . . . . . . . . . . . . . . . 6
	13.3. Link Relation: http://maven.apache.org/rel/sha1 . . . . . 5		10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
	13.4. Media Type: text/vnd.maven.pom . . . . . . . . . . . . . 5		10.1. Link Relation: http://maven.apache.org/rel/pom . . . . . 6
	13.5. Media Type: text/vnd.maven.md5 . . . . . . . . . . . . . 5		10.2. Link Relation: http://maven.apache.org/rel/md5 . . . . . 6
	13.6. Media Type: text/vnd.maven.sha1 . . . . . . . . . . . . . 5		10.3. Link Relation: http://maven.apache.org/rel/sha1 . . . . . 6
	14. Appendix: References . . . . . . . . . . . . . . . . . . . . . 5		10.4. Media Type: text/vnd.maven.pom . . . . . . . . . . . . . 6
	15. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 6		10.5. Media Type: text/vnd.maven.md5 . . . . . . . . . . . . . 6
	16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6		10.6. Media Type: text/vnd.maven.sha1 . . . . . . . . . . . . . 6
	17. Security Considerations . . . . . . . . . . . . . . . . . . . 6		11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 6
	18. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6		12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
	Appendix A. References . . . . . . . . . . . . . . . . . . . . . . 7		13. Security Considerations . . . . . . . . . . . . . . . . . . . 6
	Appendix A.1. Normative References . . . . . . . . . . . . . . 7		14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6
	Appendix A.2. Informative References . . . . . . . . . . . . . 7		14.1. Normative References . . . . . . . . . . . . . . . . . . 6
			14.2. Informative References . . . . . . . . . . . . . . . . . 7
	Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 7		Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 7
	1. TODOs and Notes		1. TODOs and Notes
	o Is it useful to register "Maven Coordinate" HTTP header? Maven-		o Is it useful to register "Maven Coordinate" HTTP header? Maven-
	Coordinate: groupId=com.example, artifactId=example, type=jar,		Coordinate: groupId=com.example, artifactId=example, type=jar,
	classifiers=awesome, version=1.2.3		classifiers=awesome, version=1.2.3
	o Promising media types and link relations:		o Promising media types and link relations:
	o "describedby" link relation - a link from an artifact to its POM		* "describedby" link relation - a link from an artifact to its
			POM
	o "edit" link relation describing an external form of editing.		* "edit" link relation describing an external form of editing.
	useful if we don't want to include all the edit controls inside		useful if we don't want to include all the edit controls inside
	feeds. Reduces bandwidth and latency		feeds. Reduces bandwidth and latency
	o atom and collection+json seem like nice formats for manipulating		* atom and collection+JSON seem like nice formats for
	lists of artifacts.		manipulating lists of artifacts.
	o metalink looks like a nice way to include		* metalink looks like a nice way to include
	o There are both a standalone XML format and a HTTP binding that can		+ There are both a standalone XML format and a HTTP binding
	be used. It might be feasible to include metalink inside atom and		that can be used. It might be feasible to include metalink
	possibly metalink inside collection+json		inside atom and possibly metalink inside collection+JSON
	2. Introduction		2. Introduction
	The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",		The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
	"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this		"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
	document are to be interpreted as described in RFC 2119 [RFC2119].		document are to be interpreted as described in RFC 2119 [RFC2119].
	View Source		View Source
	2.1. Goals:		2.1. Goals:
	o Any user agent should be able to rely on caching information given		o Any user agent should be able to rely on caching information given
	by the repository. No explicit caching should be necessary by the		by the repository. No explicit caching should be necessary by the
	application using a user agent for a Maven repository. In other		application using a user agent for a Maven repository. In other
	words, no ~/.m2/repository or ~/.ivy2.		words, no ~/.m2/repository or ~/.ivy2.
	o It should be possible to use standard HTTP intermediates without		o It should be possible to use standard HTTP intermediates without
	interfering. This is required to cover several use cases:		interfering. This is required to cover several use cases:
	o Teams inside a corporation might be far away from a central		* 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		repository and/or have a slow link. A local cache will be able
	answer their queries faster.		to answer their queries faster.
	o A central repository might get a very high number of requests. A		* A central repository might get a very high number of requests.
	cache next to the back-end application will help scale the		A cache next to the back-end application will help scale the
	repository as it will take load of the back-end application.		repository as it will take load of the back-end application.
	o The applications should be easy to use with current command line		o The applications should be easy to use with current command line
	clients		clients.
	2.2. Implementation goals		2.2. Implementation goals
	o There shouldn't be any need to invent lots of media types or link		o There shouldn't be any need to invent lots of media types or link
	relations. The operations should be able to fit within existing		relations. The operations should be able to fit within existing
	hyper medias.		hyper medias.
	2.3. Areas explicitly not covered		2.3. Areas explicitly not covered
	This specification will not apply to the existing static Maven		This specification will not apply to the existing static Maven
	repositories.That would be impossible within reason and there are		repositories.That would be impossible within reason and there are
	already enough tools to support that kind of repositories. However,		already enough tools to support that kind of repositories. However,
	it inside this specification to be able to create an application that		it inside this specification to be able to create an application that
	support the operations while still points to a static repository for		support the operations while still points to a static repository for
	providing the actual artifacts.		providing the actual artifacts.
	3. Operations		2.4. Deployment scenarios
			o Standalone repository - similar to nexus, Artifactory etc
			o Mirror application
			* rsync-ed copy of another repository with extra meta data
			* Partial mirror of another repository
			o 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
	o Upload artifact		o Upload artifact
	o Single files		* Single files
	o Single artifact + signatures and checksums?		* Single artifact + signatures and checksums?
	o Upload set of artifacts - ziped? multipart?		o Upload set of artifacts - zipped? multipart?
	o Move/copy artifacts between repositories		o Move/copy artifacts between repositories
	o promote artifacts from staging to test to production		* promote artifacts from staging to test to production
	o copy from internal repository to external repository		* copy from internal repository to external repository
	o Sign artifact		o Sign artifact
	o Lists of recently uploaded/changed files		o Lists of recently uploaded/changed files
	o Download bigger chunks of an archive		o Download bigger chunks of an archive
	o Download entire applications with one GET		* Download entire applications with one GET
	o Download the latest changes from a repository
			* Download the latest changes from a repository
	o Searching		o Searching
	o Search for group id, artifact id, by type, by classifier, signed		* Search for group id, artifact id, by type, by classifier,
	by		signed by
	o Search content of artifacts - find all jars with class foo.Bar,		* Search content of artifacts - find all jars with class foo.Bar,
	all classes that implement javax.servlet.Servlet		all classes that implement javax.servlet.Servlet
	4. Deployment scenarios		3.3. Uploading Artifacts
	5. Standalone repository - similar to nexus, artifactory etc		It should be possible to:
	6. Mirror application		o Upload a single artifact
	6.1. rsync-ed copy of another repository with extra metadata		o Upload a bundle of artifacts in a single upload
	6.2. Partial mirror of another repository		o Attach signatures to an artifact
	7. Security proxy of another mirror		3.4. Downloading Artifacts
	7.1. can require authentication		It should be possible to
	8. Security Aspects		3.4.1. Download a single artifact
			3.4.2. Download a set of artifacts
	8.1. Authentication and Authorization		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		Authentication and authorization is generally not specified by this
	specification as it is assumed that the transport mechanisms will		specification as it is assumed that the transport mechanisms will
	specify the different options for authentication.		specify the different options for authentication.
	9. User-Agent Considerations		6. User-Agent Considerations
	A user-agent should include information on how stale data it allows.		A user-agent should include information on how stale data it allows.
	This make it possible for caches to in		This make it possible for caches to in
	A user agent must always check that it got the data it required after		A user agent must always check that it got the data it required after
	receiving a response.		receiving a response.
	If a response include many links with the same relation and content		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		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		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		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.		same host (as defined by the URI) for the following requests.
	10. HTTP Binding		7. HTTP Binding
	Explain what extra headers can be given with each response for		Explain what extra headers can be given with each response for
	artifacts:		artifacts:
	o Checksums: MD5, SHA-1		o Checksums: MD5, SHA-1
	o Crypo signatures, either complete signatures or links to
			o Cryptographic signatures, either complete signatures or links to
	signatures		signatures
	o File size		o File size
	11. Appendix: Words and Definitions		8. Appendix: Words and Definitions
	Maven Repository A Maven Repository contain a set of artifacts. Each		Maven Repository A Maven Repository contain a set of artifacts. Each
	artifact is identified by a:		artifact is identified by a:
	* group id		* group id
	* artifact id		* artifact id
	* version		* version
	* type		* type
	* classifier - this is optional		* classifier - this is optional
	See Also (The Maven site at apache)[http://maven.apache.org]		See Also (The Maven site at apache)[http://maven.apache.org]
	12. Security Considerations		9. Security Considerations
	13. IANA Considerations		10. IANA Considerations
	o TODO: Move media types here or this section down.		o TODO: Move media types here or this section down.
	o TODO: Check if there are other checksum relations that are as		o TODO: Check if there are other checksum relations that are as
	useful. It might be possible to reuse something here. Would be		useful. It might be possible to reuse something here. Would be
	make sense to register a "text/checksum" type and assume that all		make sense to register a "text/checksum" type and assume that all
	clients can use content negotiation to find it? Should it be		clients can use content negotiation to find it? Should it be
	registered at all, or should it be assumed that the application		registered at all, or should it be assumed that the application
	always can implement rfc3230?		always can implement RFC3230?
	13.1. Link Relation: http://maven.apache.org/rel/pom		10.1. Link Relation: http://maven.apache.org/rel/pom
	A pointer to a Maven POM file.		A pointer to a Maven POM file.
	TODO: Should probably not be here, a link with rel=describedby,		TODO: Should probably not be here, a link with rel=describedby,
	contentType=text/vnd.maven.pom is probably fine.		contentType=text/vnd.maven.pom is probably fine.
	13.2. Link Relation: http://maven.apache.org/rel/md5		10.2. Link Relation: http://maven.apache.org/rel/md5
	13.3. Link Relation: http://maven.apache.org/rel/sha1
	13.4. Media Type: text/vnd.maven.pom
	13.5. Media Type: text/vnd.maven.md5
	13.6. Media Type: text/vnd.maven.sha1
	14. Appendix: References
	TODO: Figure out which links that are informative vs normative. See
	http://www.ietf.org/iesg/statement/normative-informative.html.
	o HTTP
	o Fielding's dissertation that describe REST
	o RFC containing definition of MAY, MUST, SHOULD etc
	o MD5
	o SHA-1
	o JSON
	o HTML
	o Atom [RFC4287]
	o TODO: Add reference to "POM"		10.3. Link Relation: http://maven.apache.org/rel/sha1
	o [RFC6249: Metalink/HTTP: Mirrors and Hashes|http://tools.ietf.org/		10.4. Media Type: text/vnd.maven.pom
	html/rfc6249]
	o [RFC5854: The Metalink Download Description Format|http://		10.5. Media Type: text/vnd.maven.md5
	tools.ietf.org/html/rfc5854]
	o [RFC1864: The Content-MD5 Header Field|http://tools.ietf.org/html/		10.6. Media Type: text/vnd.maven.sha1
	rfc1864]
	o [RFC3230: Instance Digests in HTTP|http://tools.ietf.org/html/		11. Acknowledgments
	rfc3230]
	15. Acknowledgements		12. IANA Considerations
	16. IANA Considerations		13. Security Considerations
	17. Security Considerations		14. References
	18. References		14.1. Normative References
	[RFC1864] Myers, J. and M. Rose, "The Content-MD5 Header Field", RFC		[RFC1864] Myers, J. and M. Rose, "The Content-MD5 Header Field", RFC
	1864, October 1995.		1864, October 1995.
	[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate		[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
	Requirement Levels", BCP 14, RFC 2119, March 1997.		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		[RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", RFC
	3230, January 2002.		3230, January 2002.
	[RFC4287] Nottingham, M.Ed., and R. Sayre, Ed., "The Atom		[RFC4287] Nottingham, M.Ed., and R. Sayre, Ed., "The Atom
	Syndication Format", RFC 4287, December 2005.		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		[RFC5854] Bryan, A., Tsujikawa, T., McNab, N. and P. Poeml, "The
	Metalink Download Description Format", RFC 5854, June		Metalink Download Description Format", RFC 5854, June
	2010.		2010.
	[RFC6249] Bryan, A., McNab, N., Tsujikawa, T., Poeml, P. and H.		[RFC6249] Bryan, A., McNab, N., Tsujikawa, T., Poeml, P. and H.
	Nordstrom, "Metalink/HTTP: Mirrors and Hashes", RFC 6249,		Nordstrom, "Metalink/HTTP: Mirrors and Hashes", RFC 6249,
	June 2011.		June 2011.
	Appendix A. References		14.2. Informative References
	Appendix A.1. Normative References		[RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321,
			April 1992.
	Appendix A.2. Informative References		[RFC3174] Eastlake, D. and P. Jones, "US Secure Hash Algorithm 1
			(SHA1)", RFC 3174, September 2001.
	Author's Address		Author's Address
	Trygve		Trygve
	Arktekk		Arktekk
	NO		NO
	Phone: +47 926 99 070		Phone: +47 926 99 070
	Email: trygvis@inamo.no		Email: trygvis@inamo.no
End of changes. 50 change blocks.
	120 lines changed or deleted		137 lines changed or added
This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/