The following a working idea for the structure of the REST API for eBAGIS. As it stands, this structure is not implemented, so this page is not intended as documentation for testing the API, but as a guide for architecting the API.
The main data-related functions I could think of are these:
List all AOIs
Download an AOI
Upload an AOI
Update an AOI record
Delete an AOI
Get the record of a "Geodatabase" in an AOI
Update a Geodatabase record in an AOI
Get a list of layers of a specific type from a Geodatabase in an AOI
Get a specific layer in a Geodatabase in an AOI
Add a new layer to a Geodatabase in an AOI
Update a layer in a Geodatabase in an AOI
Perform the same operations on a "Directory" in an AOI as available for a Geodatabase, except with "Files", not layers
If required functions are missing from this list, please comment and I will update the API design as needed.
Base API URL
https://webservices.geog.pdx.edu/api/rest
AOI Endpoints
GET /aois -- list of AOIs in database
GET /aois/pk -- retrieve a specific AOI in the database (pk is primary key); I'm thinking this is the endpoint to download an AOI, likely with an optional parameter specifying a download rather than the AOI record.
POST /aois -- add AOI .zip to database (honestly, I am unsure if this is possible, given the processing that needs to happen on the server side. I may need to create a separate endpoint just for uploads, as I have for testing. Update: more research suggests this is possible. What would happen is that an upload will return a link to another endpoint the could be polled by the client to find out the processing progress and/or success/failure for the upload. If it is successful then the endpoint would return a link to the AOI record as created.)
PUT /aois/pk -- update editable fields on an AOI
DELETE /aois/pk -- remove AOI from database
Geodatabase Endpoints
GET /aois/pk/layers -- get the record of the layers "GDB" under a specific AOI; replace layers with the name of any GDB in the AOI
PUT /aoi/pk/layers -- update editable fields on a "GDB"
POST and DELETE methods are not implemented on geodatabase endpoints except HRUs (unless they need to be implemented on others too; the details of these operations are still under consideration).
Layer Endpoints
GET /aois/pk/layers/rasters -- get the list of raster layers in the "GDB" specified
GET /aois/pk/layers/tables -- get the list of tables in the "GDB" specified
GET /aois/pk/layers/vectors -- get the list of vector layers in the "GDB" specified
GET /aois/pk/layers/rasters/pk -- get a specific raster layer in the "GDB" specified (not sure if these methods should provide means to download a layer or just return the record)
GET /aois/pk/layers/tables/pk -- get a specific table in the "GDB" specified
GET /aois/pk/layers/vectors/pk -- get a specific vector layer in the "GDB" specified
POST /aois/pk/layers/rasters -- add a raster layer to the "GDB" specified
POST /aois/pk/layers/tables -- add a table to the "GDB" specified
POST /aois/pk/layers/vectors -- add a vector layer to the "GDB" specified
PUT /aois/pk/layers/rasters/pk -- update a specific raster layer in the "GDB" specified
PUT /aois/pk/layers/tables/pk -- update a specific table in the "GDB" specified
PUT /aois/pk/layers/vectors/pk -- update a specific vector layer in the "GDB" specified
NOTE: HRU geodatabases are unique in that they can store one XML file as well as the other layers
Directory Endpoints
GET /aois/pk/maps -- get the record of the map document directory under a specific AOI; replace layers with the name of any subfolder of the AOI
PUT /aoi/pk/maps -- update editable fields on a directory
POST and DELETE methods are not implemented on directory endpoints.
File Endpoints
GET /aois/pk/maps/mapdocs -- get the list of map documents in the maps directory
GET /aois/pk/zones/hrus -- get the list of HRUs in the zones directory
GET /aois/pk/maps/mapdocs/pk -- get a specific map document in the maps directory (not sure if these methods should provide means to download the file or just return the record)
GET /aois/pk/zones/hrus/pk -- get a specific HRU in the zones directory
POST /aois/pk/maps/mapdocs -- add a map document to the maps directory
POST /aois/pk/zones/hrus -- add an HRU to the zones directory
PUT /aois/pk/maps/mapdocs/pk -- update a specific map document in the maps directory
PUT /aois/pk/zones/hrus/pk -- update a specific HRU in the zones directory
Users and Groups
GET /users -- retrieve a list of all users
POST /users -- add a user
User Tokens and Authorization
POST /api-token-auth -- post a username and password to this endpoint and get the user's token for authentication
GET /api-token-test -- place a request to this endpoint with a token in the header to test the validity of the token; dummy endpoint does nothing except returns a status
OPTIONS Requests
Sending an HTTP OPTIONS request to any endpoint should return a meaningful description of the endpoint and details about what it provides, how to use it, etc.