draft-laugstol-apache-maven-repository-rest-applications-07.txt		draft-laugstol-apache-maven-repository-rest-applications-08.txt
	skipping to change at page 1, line 39		skipping to change at page 1, line 39
	Internet-Drafts are draft documents valid for a maximum of six months		Internet-Drafts are draft documents valid for a maximum of six months
	and may be updated, replaced, or obsoleted by other documents at any		and may be updated, replaced, or obsoleted by other documents at any
	time. It is inappropriate to use Internet-Drafts as reference		time. It is inappropriate to use Internet-Drafts as reference
	material or to cite them other than as "work in progress."		material or to cite them other than as "work in progress."
	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
			1.1. Artifact Repository . . . . . . . . . . . . . . . . . . . 3
	2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3		2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
	2.1. Goals: . . . . . . . . . . . . . . . . . . . . . . . . . . 3		2.1. Goals: . . . . . . . . . . . . . . . . . . . . . . . . . . 3
	2.2. Implementation goals . . . . . . . . . . . . . . . . . . . 4		2.2. Implementation goals . . . . . . . . . . . . . . . . . . . 4
	2.3. Areas explicitly not covered . . . . . . . . . . . . . . . 4		2.3. Areas explicitly not covered . . . . . . . . . . . . . . . 4
	2.4. Deployment scenarios . . . . . . . . . . . . . . . . . . . 4		2.4. Deployment scenarios . . . . . . . . . . . . . . . . . . . 4
	3. Specification . . . . . . . . . . . . . . . . . . . . . . . . 4		3. Specification . . . . . . . . . . . . . . . . . . . . . . . . 4
	3.1. Media Types . . . . . . . . . . . . . . . . . . . . . . . 4		3.1. Repository Concepts . . . . . . . . . . . . . . . . . . . 4
	3.2. Operations . . . . . . . . . . . . . . . . . . . . . . . . 4		3.2. Media Types . . . . . . . . . . . . . . . . . . . . . . . 5
	3.3. Uploading Artifacts . . . . . . . . . . . . . . . . . . . 5		3.3. Operations . . . . . . . . . . . . . . . . . . . . . . . . 5
	3.4. Downloading Artifacts . . . . . . . . . . . . . . . . . . 5		3.4. Uploading Artifacts . . . . . . . . . . . . . . . . . . . 5
	3.4.1. Download a single artifact . . . . . . . . . . . . . . 5		3.5. Downloading Artifacts . . . . . . . . . . . . . . . . . . 6
	3.4.2. Download a set of artifacts . . . . . . . . . . . . . 6		3.5.1. Download a single artifact . . . . . . . . . . . . . . 6
	3.5. Searching . . . . . . . . . . . . . . . . . . . . . . . . 6		3.5.2. Download a set of artifacts . . . . . . . . . . . . . 6
	3.6. List Repositories . . . . . . . . . . . . . . . . . . . . 6		3.6. Searching . . . . . . . . . . . . . . . . . . . . . . . . 6
			3.7. List Repositories . . . . . . . . . . . . . . . . . . . . 6
	4. Security Aspects . . . . . . . . . . . . . . . . . . . . . . . 6		4. Security Aspects . . . . . . . . . . . . . . . . . . . . . . . 6
	4.1. Authentication and Authorization . . . . . . . . . . . . . 6		4.1. Authentication and Authorization . . . . . . . . . . . . . 6
	5. User-Agent Considerations . . . . . . . . . . . . . . . . . . 6		5. User-Agent Considerations . . . . . . . . . . . . . . . . . . 6
	5.1. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 6		5.1. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 6
	5.2. Multiple links . . . . . . . . . . . . . . . . . . . . . . 7		5.2. Multiple links . . . . . . . . . . . . . . . . . . . . . . 7
	5.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . . . 7		5.3. Forms . . . . . . . . . . . . . . . . . . . . . . . . . . 7
	5.4. Server Responses . . . . . . . . . . . . . . . . . . . . . 7		5.4. Server Responses . . . . . . . . . . . . . . . . . . . . . 7
	5.4.1. Single Artifact . . . . . . . . . . . . . . . . . . . 7		5.4.1. Single Artifact . . . . . . . . . . . . . . . . . . . 7
	5.4.2. Multiple Artifacts . . . . . . . . . . . . . . . . . . 7		5.4.2. Multiple Artifacts . . . . . . . . . . . . . . . . . . 7
	5.4.2.1. text/uri-list . . . . . . . . . . . . . . . . . . 7		5.4.2.1. text/uri-list . . . . . . . . . . . . . . . . . . 8
	5.5. HTTP Binding . . . . . . . . . . . . . . . . . . . . . . . 7		5.5. HTTP Binding . . . . . . . . . . . . . . . . . . . . . . . 8
	6. Appendix: Words and Definitions . . . . . . . . . . . . . . . 8		6. Appendix: Words and Definitions . . . . . . . . . . . . . . . 8
	7. Security Considerations . . . . . . . . . . . . . . . . . . . 8		7. Security Considerations . . . . . . . . . . . . . . . . . . . 8
	8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8		8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
	8.1. Link Relation: http://maven.apache.org/rel/pom . . . . . . 8		8.1. Link Relation: http://maven.apache.org/rel/pom . . . . . . 9
	8.2. Link Relation: http://maven.apache.org/rel/md5 . . . . . . 8		8.2. Link Relation: http://maven.apache.org/rel/md5 . . . . . . 9
	8.3. Link Relation: http://maven.apache.org/rel/sha1 . . . . . 8		8.3. Link Relation: http://maven.apache.org/rel/sha1 . . . . . 9
	8.4. Media Type: text/vnd.maven.pom . . . . . . . . . . . . . . 8		8.4. Media Type: text/vnd.maven.pom . . . . . . . . . . . . . . 9
	8.5. Media Type: text/vnd.maven.md5 . . . . . . . . . . . . . . 8		8.5. Media Type: text/vnd.maven.md5 . . . . . . . . . . . . . . 9
	8.6. Media Type: text/vnd.maven.sha1 . . . . . . . . . . . . . 8		8.6. Media Type: text/vnd.maven.sha1 . . . . . . . . . . . . . 9
	8.7. URN Registration: urn:maven:artifact . . . . . . . . . . . 8		8.7. URN Registration: urn:maven:artifact . . . . . . . . . . . 9
	9. Security Considerations . . . . . . . . . . . . . . . . . . . 9		9. Security Considerations . . . . . . . . . . . . . . . . . . . 9
	10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 9		10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 9
	11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9		11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9
	11.1. Normative References . . . . . . . . . . . . . . . . . . 9		11.1. Normative References . . . . . . . . . . . . . . . . . . 9
	11.2. Informative References . . . . . . . . . . . . . . . . . 9		11.2. Informative References . . . . . . . . . . . . . . . . . 10
	Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10		Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10
	1. TODOs and Notes		1. TODOs and Notes
	o How should an artifact be identified?		o How should an artifact be identified?
	* A "Maven Coordinate" HTTP header? Maven-Coordinate:		* A "Maven Coordinate" HTTP header? Maven-Coordinate:
	groupId=com.example, artifactId=example, type=jar,		groupId=com.example, artifactId=example, type=jar,
	classifiers=awesome, version=1.2.3		classifiers=awesome, version=1.2.3
	skipping to change at page 2, line 57		skipping to change at page 3, line 4
	POM		POM
	* "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
	* atom and collection+JSON seem like nice formats for		* atom and collection+JSON seem like nice formats for
	manipulating lists of artifacts.		manipulating lists of artifacts.
	* metalink looks like a nice way to include		* metalink looks like a nice way to include
	+ There are both a standalone XML format and a HTTP binding		+ There are both a standalone XML format and a HTTP binding
	that can be used. It might be feasible to include metalink		that can be used. It might be feasible to include metalink
	inside atom and possibly metalink inside collection+JSON		inside atom and possibly metalink inside collection+JSON
	o Should this whole thing be turned into a more generic "artifact		* Put this where it'll fit later
	repository". This would make it easier to support repositories
	for particular scala versions (so you won't have to highjack		+ It is assumed that there will always only be a single
	Maven's semantics with "artifactId = realArtifactId + "_" +		instance of an artifact + version. If two repositories can
	scalaVersion".		resolve the same artifact any user agent can choose
			arbitrary which one it'll like to use.
			+ This is important as some people download an artifact from
			one repository, modify it and upload it to another
			repository. This is sometimes done by operations when they
			consume artifacts from a "developer" repository, inject some
			configuration variables and pushes it to a "production"
			repository.
			1.1. Artifact Repository
			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		It would also be easier to add support for extra attributes like
	"build number", "jenkins build", "henkins job name" and "build		"build number", "jenkins build", "henkins job name" and "build
	timestamp".		timestamp".
	How should these attributes be describes? One possible option is a		How should these attributes be describes? One possible option is a
	"profile" per repository that describe the possible attributs. You'd		"profile" per repository that describe the possible attributs. You'd
	get a "maven profile", "jenkins profile"/"ci profile" etc. Does the		get a "maven profile", "jenkins profile"/"ci profile" etc. Does the
	values imply special values? Could a "maven profile" specify that		values imply special values? Could a "maven profile" specify that
	'if you upload an artifact with "build-number" set to "next" the		'if you upload an artifact with "build-number" set to "next" the
	server will pick the next available build number'. Having the server		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		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		agents, but at the same time you're specifying semantics that are to
	be valid for all times.		be valid for all times.
	Put this where it'll fit later: It is assumed that there will always		I guess it all comes down to how much should be put in as attachments
	only be a single instance of an artifact + version. If two		to an artifact vs how much should these applications be involved.
	repositories can resolve the same artifact any user agent can choose
	arbitrary which one it'll like to use.
	This is important as some people download an artifact from one		If this is to be done specify bindings for Maven Artifacts, Scala
	repository, modify it and upload it to another repository. This is		Artifacts (basically Maven Artifacts + scala version), Sbt Plugin
	sometimes done by operations when they consume artifacts from a		Artifacts, Debian packages, OpenCSW packages.
	"developer" repository, inject some configuration variables and
	pushes it to a "production" repository.
	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].
	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
	skipping to change at page 4, line 42		skipping to change at page 5, line 4
	* rsync-ed copy of another repository with extra meta data		* rsync-ed copy of another repository with extra meta data
	* Partial mirror of another repository		* Partial mirror of another repository
	o Security proxy of another mirror		o Security proxy of another mirror
	* can require authentication		* can require authentication
	3. Specification		3. Specification
			3.1. Repository Concepts
	3.1. Media Types		o An artifact can reside in many repositories.
			o An artifact has a permanent form and will never change. If you
			get artifact X from repository A or B doesn't matter.
			o An artifact can have many "builds". Each build has a timestamp.
			3.2. Media Types
	TODO: Find a reference to @mamund's "you should always design a new		TODO: Find a reference to @mamund's "you should always design a new
	media type (but not format)".		media type (but not format)".
	3.2. Operations		3.3. Operations
	o Upload artifact		o Upload artifact
	* Single files		* Single files
	* Single artifact + signatures and checksums?		* Single artifact + signatures and checksums?
	o Upload set of artifacts - zipped? multipart?		o Upload set of artifacts - zipped? multipart?
	o Move/copy artifacts between repositories		o Move/copy artifacts between repositories
	* promote artifacts from staging to test to production		* promote artifacts from staging to test to production
	* 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
	skipping to change at page 5, line 28		skipping to change at page 5, line 52
	* Download the latest changes from a repository		* Download the latest changes from a repository
	o Searching		o Searching
	* Search for group id, artifact id, by type, by classifier,		* Search for group id, artifact id, by type, by classifier,
	signed by		signed by
	* 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
	3.3. Uploading Artifacts		3.4. Uploading Artifacts
	It should be possible to:		It should be possible to:
	o Upload a single artifact		o Upload a single artifact
	o Upload a bundle of artifacts in a single upload		o Upload a bundle of artifacts in a single upload
	o Attach signatures to an artifact		o Attach signatures to an artifact
	3.4. Downloading Artifacts		3.5. Downloading Artifacts
	3.4.1. Download a single artifact		3.5.1. Download a single artifact
	Steps to download a single artifact with a specific version:		Steps to download a single artifact with a specific version:
	Download the start resource and find a form named "download-		Download the start resource and find a form named "download-
	artifact".		artifact".
	Artifacts can be identified either through an artifact URN or a full		Artifacts can be identified either through an artifact URN or a full
	set of coordinates. To use the URN mechanism fill out the "urn"		set of coordinates. To use the URN mechanism fill out the "urn"
	field, to use the coordinate version fill out the fields named		field, to use the coordinate version fill out the fields named
	"groupId", "artifactId", "version", "type" and "classifier". The		"groupId", "artifactId", "version", "type" and "classifier". The
	"classifier" field is optional. These fields MUST be present in the		"classifier" field is optional. These fields MUST be present in the
	form.		form.
	TODO: Some possible optional controls: "filename".		TODO: Some possible optional controls: "filename".
	Submit the form. The server MAY return a single artifact, see		Submit the form. The server MAY return a single artifact, see
	Section 5.4.1.		Section 5.4.1.
	3.4.2. Download a set of artifacts		3.5.2. Download a set of artifacts
	The set might be a search, or just a list of artifacts. The server		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		is free to choose to send a container format with all the files in
	it, or just an URL list with pointers.		it, or just an URL list with pointers.
	3.5. Searching		3.6. Searching
	Servers SHOULD implement conditional controls so it's possible to		Servers SHOULD implement conditional controls so it's possible to
	poll the server regularly.		poll the server regularly.
	TODO: specify how to query for only changes after a certain		TODO: specify how to query for only changes after a certain
	timestamp.		timestamp.
	3.6. List Repositories		3.7. List Repositories
	4. Security Aspects		4. Security Aspects
	4.1. Authentication and Authorization		4.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.
	5. User-Agent Considerations		5. User-Agent Considerations
	skipping to change at page 8, line 54		skipping to change at page 9, line 24
	8.3. Link Relation: http://maven.apache.org/rel/sha1		8.3. Link Relation: http://maven.apache.org/rel/sha1
	8.4. Media Type: text/vnd.maven.pom		8.4. Media Type: text/vnd.maven.pom
	8.5. Media Type: text/vnd.maven.md5		8.5. Media Type: text/vnd.maven.md5
	8.6. Media Type: text/vnd.maven.sha1		8.6. Media Type: text/vnd.maven.sha1
	8.7. URN Registration: urn:maven:artifact		8.7. URN Registration: urn:maven:artifact
	Should it be "urn:maven:artifact" or "urn:maven"		Should it be "urn:maven:artifact", "urn:maven" or "urn:artifact-
			repository".
	Use template in http://tools.ietf.org/html/rfc3406#appendix-A		Use template in http://tools.ietf.org/html/rfc3406#appendix-A
	Creating an informal registration seems the right way to do as long		Creating an informal registration seems the right way to do as long
	as this document doesn't become an RFC.		as this document doesn't become an RFC.
			URN notes:
			o A single artifact: "urn:artifact-repository:artifact:<attributes>"
			o A search: "urn:artifact-repository:search:<attributes>"
	9. Security Considerations		9. Security Considerations
	10. Acknowledgments		10. Acknowledgments
	11. References		11. References
	11.1. Normative References		11.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.
End of changes. 23 change blocks.
	43 lines changed or deleted		72 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/