API draft spec for ceo #1

New Issue

merenber · 2021-07-03T16:39:56-04:00

merenber commented

2021-07-03 16:39:56 -04:00

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.

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.

r389li commented

2021-07-03 18:11:24 -04:00

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

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 ```

ztseguin commented

2021-07-03 18:50:24 -04:00

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

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 ```

merenber commented

2021-07-03 18:53:48 -04:00

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.

> 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.

a268wang commented

2021-07-05 20:01:53 -04:00

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

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 ```

merenber commented

2021-07-05 20:18:49 -04:00

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.

> 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.

n3parikh commented

2021-07-06 02:17:14 -04:00

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

merenber referenced this issue

2021-07-24 18:36:09 -04:00

Create /api/groups endpoint #2

merenber referenced this issue

2021-07-24 18:43:56 -04:00

Create /api/db endpoints #3

merenber commented

2021-08-29 13:12:59 -04:00

API endpoints have now all been implemented 😄