REST API

[cecilialau6776]

Spent the last day or so poking at/playing with the REST API, so I figured I'd share what I learned.

Note: This is not meant to be documentation, but please feel free to adapt it for such.

The REST API uses Django REST Framework.

Enabling REST API

1. Add PLUGIN_API=True to your coldfront.env file.
2. Run coldfront migrate to create the tables for tokens.
3. Restart services, if appropriate (systemctl restart gunicorn).

Our configuration has ColdFront behind Apache for OIDC auth, so we needed to add a few lines to our ssl.conf:

# ssl.conf
<Location /api>
   AuthType None
   OIDCUnAuthAction pass
</Location>

Getting a Token

The enabled authentication classes are TokenAuthentication and SessionAuthentication. I've not played with SessionAuthentication, so I'm not sure how to use it.

Note: According to the above docs, you should only use TokenAuthentication in production if the API is only available over https.

To get a token, you can:

• Log in to the web portal and go to your user profile (if you haven't overriden this template). There are buttons to generate a token and to copy it.
• Use the admin portal - there should be a "Tokens" section where you can create a token for any user. You can also see existing tokens here.
• Use the command line: running coldfront drf_create_token <username> will (re?)generate a token for that user.

Using the API

Authenticate calls with the Authentication: Token <token> HTTP header.
Examples:

$ curl -L -H 'Authorization: Token <token>' -H 'Accept: application/json; indent=4' https://coldfront.rc.rit.edu/api/allocations/861
{
    "id": 104,
    "project": "rc-admins",
    "resource": "SPORC Cluster",
    "status": "Active"
}

$ curl -L -H 'Authorization: Token <token>' -H 'Accept: application/json' https://coldfront.rc.rit.edu/api/users/261    
{"id":261,"username":"chlits","first_name":"Cecilia","last_name":"Lau","is_active":true,"is_superuser":true,"is_staff":true,"date_joined":"2023-08-08T13:16:41.910620-04:00"}

$ curl -L -H 'Authorization: Token <token>' -H 'Accept: application/json' https://coldfront.rc.rit.edu/api/resources/4
{"detail":"No Resource matches the given query."} # this does return HTTP 404

Endpoints

I have not tested all of these. This is just a list compiled from coldfront/plugins/api/urls.py and coldfront/plugins/api/views.py, so it's possible/likely I'm missing a few endpoints/query parameters.

Endpoints that return a list of objects appear to return all the objects the user has access to. For example, a regular user who is part of two projects would have those two projects returned when calling /api/projects. Superusers/staff would get all projects returned.

The date format is what I tried and it worked. Other formats may also work.

Allocations

• /api/allocations
  • Returns a list of allocations.
• /api/allocations/<pk>
  • Returns allocation <pk>.

Allocation Requests

• /api/allocation-requests
  • Returns a list of allocation requests.
  • Query Params:
    • created_before: date (YYYY-M-D)
    • created_after: date (YYYY-M-D)
• /api/allocation-requests/<pk>
  • Returns allocation request <pk>.

Allocation Change Requests

• /api/allocation-change-requests
  • Returns a list of allocation change requests.
• /api/allocation-change-requests/<pk>
  • Returns allocation change request <pk>.

Projects

• /api/projects
  • Returns a list of projects.
  • Query Params:
    • allocations: bool (default false)
      • Include a list of associated allocations. If false, returns null.
    • project_users: bool (default false)
      • Include a list of associated project users. If false, returns null.
• /api/projects/<pk>
  • Returns project <pk>.
  • Query Params:
    • allocations: bool (default false)
      • Include a list of associated allocations. If false, returns null.
    • project_users: bool (default false)
      • Include a list of associated project users. If false, returns null.

Resources

• /api/resources
  • Returns a list of all resources.
• /api/resources/<pk>
  • Returns resource <pk>.

Users

• /api/users/
  • Returns a list of users.
  • Query Params:
    • username: string
      • Filter by username. Must be exact.
    • is_active: bool
      • Filter by is_active.
    • is_superuser: bool
      • Filter by is_superuser.
    • is_staff: bool
      • Filter by is_staff.
• /api/users/<pk>
  • Returns user <pk>.

Misc

Looks like there's no way to get project/allocation attributes nor their usages - this may become useful for us in the future, so I may make a PR for it, but I've higher-priority items right now (such as adding tags :D).

Looks like you get redirected without a trailing / - i.e. https://coldfront.rc.rit.edu/api/users redirects to https://coldfront.rc.rit.edu/api/users/.

Looks like the API is only for getting information right now, with no way to create objects. Maybe this will be implemented in the future? I don't think our center needs it right now, so I'm unlikely to implement it myself.