From 7b2fc9b026f6d8dee83c6d14db8e9d9d2c493cf0 Mon Sep 17 00:00:00 2001 From: Max Erenberg <> Date: Sat, 23 Oct 2021 20:46:33 -0400 Subject: [PATCH] update docs --- README.md | 2 +- docs/openapi.yaml | 19 +++++++++++++++++-- docs/redoc-static.html | 10 ++++++---- 3 files changed, 24 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 8a9998b..35fa773 100644 --- a/README.md +++ b/README.md @@ -219,6 +219,6 @@ Here's an example of making a request to an endpoint which writes to LDAP: kinit # Make the request curl --negotiate -u : --service-name ceod --delegation always \ - -d '{"uid":"test_1","cn":"Test One","program":"Math","terms":["s2021"]}' \ + -d '{"uid":"test_1","cn":"Test One","given_name":"Test","sn":"One","program":"Math","terms":["s2021"]}' \ -X POST http://phosphoric-acid:9987/api/members ``` diff --git a/docs/openapi.yaml b/docs/openapi.yaml index 4ba25bd..769224a 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -52,6 +52,10 @@ paths: $ref: "#/components/schemas/UID" cn: $ref: "#/components/schemas/UserCN" + sn: + $ref: "#/components/schemas/UserSN" + given_name: + $ref: "#/components/schemas/UserGivenName" program: $ref: "#/components/schemas/Program" terms: @@ -76,7 +80,7 @@ paths: {"status": "in progress", "operation": "send_welcome_message"} {"status": "in progress", "operation": "subscribe_to_mailing_list"} {"status": "in progress", "operation": "announce_new_user"} - {"status": "completed", "result": {"cn": "Calum Dalek", "uid": "ctdalek", "uid_number": 20001, "gid_number": 20001, "login_shell": "/bin/bash", "home_directory": "/users/ctdalek", "is_club": false, "program": "MAT/Mathematics Computer Science", "terms": ["f2021"], "forwarding_addresses": ["ctdalek@uwaterloo.ca"], "password": "Wlw1wOTofERTEBlXWzR6/MZL"}} + {"status": "completed", "result": {"cn": "Calum Dalek", "given_name": "Calum", "sn": "Dalek", "uid": "ctdalek", "uid_number": 20001, "gid_number": 20001, "login_shell": "/bin/bash", "home_directory": "/users/ctdalek", "is_club": false, "program": "MAT/Mathematics Computer Science", "terms": ["f2021"], "forwarding_addresses": ["ctdalek@uwaterloo.ca"], "password": "Wlw1wOTofERTEBlXWzR6/MZL"}} /members/{username}: get: tags: ['members'] @@ -718,6 +722,14 @@ components: type: string description: Full name example: Calum Dalek + UserSN: + type: string + description: Last name + example: Dalek + UserGivenName: + type: string + description: First name + example: Calum UID: type: string description: Username @@ -753,6 +765,10 @@ components: properties: cn: $ref: "#/components/schemas/UserCN" + sn: + $ref: "#/components/schemas/UserSN" + given_name: + $ref: "#/components/schemas/UserGivenName" uid: $ref: "#/components/schemas/UID" uid_number: @@ -858,4 +874,3 @@ components: DBConnectionOrPermissionErrorResponse: <<: *ErrorResponse description: Unable to connect to database or action failed due to permissions - diff --git a/docs/redoc-static.html b/docs/redoc-static.html index 00ee29e..a038043 100644 --- a/docs/redoc-static.html +++ b/docs/redoc-static.html @@ -467,24 +467,26 @@ curl --negotiate

Create a new user

Creates a new member or club rep. If terms is specified, a member is created; if non_member_terms is specified, a club rep is created.

Authorizations:
GSSAPIAuth
Request Body schema: application/json
uid
string (UID)

Username

cn
string (UserCN)

Full name

+
sn
string (UserSN)

Last name

+
given_name
string (UserGivenName)

First name

program
string (Program)

Academic program

terms
Array of strings (Terms)

Terms for which this user was a member

non_member_terms
Array of strings (NonMemberTerms)

Terms for which this user was a club rep

forwarding_addresses
Array of strings <email> (ForwardingAddresses)

Forwarding addresses in ~/.forward

Responses

Request samples

Content type
application/json
{
  • "uid": "ctdalek",
  • "cn": "Calum Dalek",
  • "program": "MAT/Mathematics Computer Science",
  • "terms": [
    ],
  • "non_member_terms": [
    ],
  • "forwarding_addresses": [
    ]
}

Response samples

Content type
text/plain
{"status": "in progress", "operation": "add_user_to_ldap"}
+

Request samples

Content type
application/json
{
  • "uid": "ctdalek",
  • "cn": "Calum Dalek",
  • "sn": "Dalek",
  • "given_name": "Calum",
  • "program": "MAT/Mathematics Computer Science",
  • "terms": [
    ],
  • "non_member_terms": [
    ],
  • "forwarding_addresses": [
    ]
}

Response samples

Content type
text/plain
{"status": "in progress", "operation": "add_user_to_ldap"}
 {"status": "in progress", "operation": "add_group_to_ldap"}
 {"status": "in progress", "operation": "add_user_to_kerberos"}
 {"status": "in progress", "operation": "create_home_dir"}
 {"status": "in progress", "operation": "send_welcome_message"}
 {"status": "in progress", "operation": "subscribe_to_mailing_list"}
 {"status": "in progress", "operation": "announce_new_user"}
-{"status": "completed", "result": {"cn": "Calum Dalek", "uid": "ctdalek", "uid_number": 20001, "gid_number": 20001, "login_shell": "/bin/bash", "home_directory": "/users/ctdalek", "is_club": false, "program": "MAT/Mathematics Computer Science", "terms": ["f2021"], "forwarding_addresses": ["ctdalek@uwaterloo.ca"], "password": "Wlw1wOTofERTEBlXWzR6/MZL"}}
+{"status": "completed", "result": {"cn": "Calum Dalek", "given_name": "Calum", "sn": "Dalek", "uid": "ctdalek", "uid_number": 20001, "gid_number": 20001, "login_shell": "/bin/bash", "home_directory": "/users/ctdalek", "is_club": false, "program": "MAT/Mathematics Computer Science", "terms": ["f2021"], "forwarding_addresses": ["ctdalek@uwaterloo.ca"], "password": "Wlw1wOTofERTEBlXWzR6/MZL"}}

Get information about a user

Returns information about a member or club rep. The forwarding_addresses field will only be present if the client is an authenticated syscom member.

Authorizations:
GSSAPIAuth
path Parameters
username
required
string

username of the user to return

Responses

Response samples

Content type
application/json
{
  • "cn": "Calum Dalek",
  • "uid": "ctdalek",
  • "uid_number": 20001,
  • "gid_number": 20001,
  • "home_directory": "/users/ctdalek",
  • "is_club": false,
  • "login_shell": "/bin/bash",
  • "program": "MAT/Mathematics Computer Science",
  • "positions": [
    ],
  • "terms": [
    ],
  • "non_member_terms": [
    ],
  • "forwarding_addresses": [
    ]
}

Modify a user

Replace the login shell and/or forwarding addresses of a user

+

Response samples

Content type
application/json
{
  • "cn": "Calum Dalek",
  • "sn": "Dalek",
  • "given_name": "Calum",
  • "uid": "ctdalek",
  • "uid_number": 20001,
  • "gid_number": 20001,
  • "home_directory": "/users/ctdalek",
  • "is_club": false,
  • "login_shell": "/bin/bash",
  • "program": "MAT/Mathematics Computer Science",
  • "positions": [
    ],
  • "terms": [
    ],
  • "non_member_terms": [
    ],
  • "forwarding_addresses": [
    ]
}

Modify a user

Replace the login shell and/or forwarding addresses of a user

Authorizations:
GSSAPIAuth
path Parameters
username
required
string

username of the user to modify

Request Body schema: application/json
login_shell
string (LoginShell)

Login shell

forwarding_addresses
Array of strings <email> (ForwardingAddresses)

Forwarding addresses in ~/.forward

@@ -597,7 +599,7 @@ The JSON request body may be omitted.

{"status": "completed", "result": "OK"}