API Documentation for basic repository operations lightly misleading

[triplingual]

Expected Behavior

There are 3 endpoints in the API for a certain set of basic repository work: retrieve 1 by ID, update 1 by ID, delete 1 by ID. In the documentation, the parameter for each should be listed as :repo_id.

Current Behavior

Currently, the parameter for the first two is listed as :id but for the third is given as :repo_id.

Possible Solution

Looks to me like the change would happen at

archivesspace/backend/app/controllers/repository.rb

Lines 93 to 101 in 88e9e61

	Endpoint.post('/repositories/:id')
	.description("Update a repository")
	.params(["id", :id],
	["repository", JSONModel(:repository), "The updated record", :body => true])
	.permissions([:create_repository])
	.returns([200, :updated]) \
	do
	handle_update(Repository, params[:id], params[:repository])
	end

for the update endpoint and

archivesspace/backend/app/controllers/repository.rb

Lines 143 to 153 in 88e9e61

	Endpoint.get('/repositories/:id')
	.description("Get a Repository by ID")
	.params(["id", :id],
	["resolve", :resolve])
	.permissions([])
	.returns([200, "(:repository)"],
	[404, "Not found"]) \
	do
	json_response(resolve_references(Repository.to_jsonmodel(Repository.get_or_die(params[:id])),
	params[:resolve]))
	end

for the retrieve endpoint. It wouldn't be hard for me to change the code, but I am insufficiently familiar with likely downstream effects or other side-effects.

Steps to Reproduce (for bugs)

Read the API Reference starting at the Update endpoint's entry.

Context

This came up when trying to create an API definition file for our infosec department to use in scanning the ArchivesSpace API for security. A validator for Swagger-style YAML pointed out the semantic identity of the endpoints using :id to the one using :repo_id. Correcting the YAML was easy enough, but it seems like it should be corrected more permanently if possible.

Your Environment

• Version used: API Reference says it's for 3.3.0
• Environment name and version (e.g. Chrome 39, node.js 5.4): n/a
• Operating System and version (desktop or mobile): n/a
• Link to your project: n/a