Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

API Documentation for basic repository operations lightly misleading #3066

Open
triplingual opened this issue Oct 25, 2023 · 0 comments
Open

Comments

@triplingual
Copy link

triplingual commented Oct 25, 2023

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

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
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant