search

USACE / cwms-data-api

Corps Water Management System RESTful Data Service
MIT License
13 stars 14 forks source link

Alteration to various end points to take the office id as a query parameter #414

Open MikeNeilson opened 1 year ago

MikeNeilson commented 1 year ago

While talking @ktarbet through how some of the API works I think I've stumbled upon a better way to handle the office-id for the objects.

currently for, say locations, we have

/locations/Alder Springs?office-id=SPK to retrieve the information for one location.

it seems like it would be better if we had /location/SPK/Alder Springs to retrieve information for one location

and perhaps

/locations/SPK to retrieve all locations for SPK. Currently we have the catalog but that was really more because I couldn't think of a better away at the time with the existing functionality in the database but since that's going away eventually this would be a good replacement.

All the other parameters would be the same.

adamkorynta commented 1 year ago

Would that path parameter be optional for district local instances?

I definitely like the idea for a specific resource as the getOne methods are to specific coordinates. The getAll methods, though, usually combine all the query parameters together into a search criteria (regex or wildcard office support) so I see an argument for leaving that as a query parameter.

MikeNeilson commented 1 year ago

No, but only because long term there wouldn't be local office instances. Until then we wouldn't take the current path away.

The other query parameters do need to exist. arguably for what you've presented there they can really both exist but I'm not sure how that would be handled actually. Perhaps just having two handlers one with and one without the office placeholder.