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.

Sign up for GitHub

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

Jump to bottom

API Documentation for basic repository operations lightly misleading #3066

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

API Documentation for basic repository operations lightly misleading #3066

triplingual opened this issue Oct 25, 2023 · 0 comments

Comments

@triplingual
Copy link

triplingual commented Oct 25, 2023 •
edited
Loading

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

No branches or pull requests
1 participant
@triplingual