API draft spec for ceo #1

Here is a draft proposal for the new ceo API spec:

Last Update: 2021-08-18

GET    /api/members                             get a list of members (supports search params)
POST   /api/members                             create a new member or club rep
GET    /api/members/:username                   get a specific member
PATCH  /api/members/:username                   change a member's attributes (login shell, forwarding addresses)
POST   /api/members/:username/renew             renew a member or club rep
POST   /api/members/:username/pwreset           reset a member's password

POST   /api/uwldap/:username                    get user information from uwldap
POST   /api/uwldap/updateprograms               sync the 'program' LDAP attribute with uwldap

POST   /api/groups                              create a new club/group
GET    /api/groups/:group                       get a group and its members
POST   /api/groups/:group/members/:username     add a member to a club/group
DELETE /api/groups/:group/members/:username     remove a member from a club/group

GET    /api/positions                           get the usernames for each club position
POST   /api/positions                           assign members to club positions
POST   /api/db/mysql                            create a new MySQL database for a user
POST   /api/db/postgresql                       create a new PostgresSQL database for a user

POST   /api/mailman/:list/:username             subscribe a member to a mailing list
DELETE /api/mailman/:list/:username             unsubscribe a member from a mailing list

Please leave your feedback in the comments.

We should add password resets and changes, and automatically generate secure passwords for those and on account creation. We can also use only one HTTP method per endpoint to make things clearer. Here's my proposal:

GET    /api/members                    get a list of members (supports search params)
POST   /api/members/new                create a new member or club rep
PUT    /api/members/:username/renew    renew a member or club rep
PUT    /api/members/:username/chsh     change the login shell of a member
POST   /api/members/updateprograms     sync the 'program' LDAP attribute with uwldap

POST   /api/groups/:group              create a new club/group
GET    /api/groups/:group/members      get a list of group/club members
PUT    /api/groups/:group/members/add  add a member to a club/group
DELETE /api/groups/:group/members/del  remove a member from a club/group

PUT    /api/positions                  assign members to club positions
PUT    /api/db/:username               create a new MySQL database for the user

At first glance these are my comments:

Members

I would probably change

PUT    /api/members/:username/chsh  change the login shell of a member

to

PUT    /api/members/:username  update a member

(you would need to restrict which fields can be changed by admin and/or non-admin users)

Databases

PUT    /api/db/:username            create a new MySQL database for the user

I might propose that this be broken up to:

PUT    /api/db/mysql/:username            create a new MySQL database for the user
PUT    /api/db/postgresql/:username            create a new PostgresQL database for the user

We just haven't built the postgres stuff into ceo yet, and since you're looking at re-writing it now seems like a better time than ever to integrate that.

Groups

Additionally,

POST   /api/groups/:group           create a new club/group
PUT    /api/groups/:group/members   add a member to a club/group
DELETE /api/groups/:group/members   remove a member from a club/group
GET    /api/groups/:group/members   get a list of group/club members

If we're aiming for RESTful API, then I believe the correct order for this is:

POST   /api/groups/:group                     create a new club/group
PUT    /api/groups/:group                     update a club/group
POST   /api/groups/:group/members             add a member to a club/group
DELETE /api/groups/:group/members/:username   remove a member from a club/group
GET    /api/groups/:group/members             get a list of group/club members

We should add password resets and changes, and automatically generate secure passwords for those and on account creation.

Good idea. I propose a POST endpoint to /api/members/pwreset. When a new member is created, the backend should also take care of creating a password and expiring it.

I guess here is attempt at this:

Members

GET   /api/members                            get a list of members (supports search params)
POST  /api/members                            create a new member
PUT   /api/members/<username>                 modify member details (includes chsh)
PUT   /api/members/<username>/renew           renew a member
PUT   /api/members/<username>/passwd          reset a member's password and expire it
POST  /api/members/updateprograms             sync the 'program' LDAP attribute with uwldap
POST  /api/members/<username>/db/mysql        create new MySQL database for member
POST  /api/members/<username>/db/postgresql   create new PostgresQL database for member

Alternatively we could POST the the database we want to create so we will only need

POST   /api/members/<username>/newdb        create new database for member

Groups

POST   /api/groups                                      create a new club/group
PUT    /api/groups/<group>                              update a club/group
GET    /api/groups/<group>/members                      list of members (also fetch by position)
POST   /api/groups/<group>/members/<username>           add member to a club/group
DELETE /api/groups/<group>/members/<username>           remove a member from a club/group
PUT    /api/groups/<group>/members/<username>/position  modify member's position in club

Alternatively we could use PUT to update the position of a member in a club (and do other stuff)

PUT    /api/groups/<group>/members/<username>           modify member's position in club

Also we could move the renew to renew based on clubs/groups

PUT   /api/groups/<group>/members/<username>/renew           renew a member for a club

Alternatively we could POST the the database we want to create so we will only need
POST   /api/members/<username>/newdb        create new database for member

I think I prefer using /api/db since we are performing an operation on a RDBMS and not on a Unix account.

Alternatively we could use PUT to update the position of a member in a club (and do other stuff)
PUT    /api/groups/<group>/members/<username>           modify member's position in club 

We only keep track of whether a member is in a group or not.
On a side note though, I think POST is more appropriate here, after looking at other APIs which insert members into groups.

Also we could move the renew to renew based on clubs/groups
PUT   /api/groups/<group>/members/<username>/renew           renew a member for a club

There are only two types of renewals: for CSC members and for club reps. A rep can belong to multiple clubs, or even none at all. So I think that keeping the renewals in /api/members makes more sense.

We should also support changing the forwarding email. It would probably fall under the PUT update endpoint.

API endpoints have now all been implemented 😄