Skip to content

api-endpoints.md

Latest commit

 

History

History
260 lines (208 loc) · 7.86 KB

api-endpoints.md

File metadata and controls

260 lines (208 loc) · 7.86 KB

API Endpoints

All endpoints are served on port 8080 and require a JWT Authorization: Bearer <token> header unless noted.

Base URL (local): http://localhost:8080

Endpoint Summary

Health

Method Path Auth Description
GET /livez None Liveness probe — returns OK
GET /readyz None Readiness probe — returns OK or 503

GroupsIO Services

Method Path Auth Description
GET /groupsio/services JWT List services, optionally filtered by ?project_uid=<uuid>
POST /groupsio/services JWT Create a service
GET /groupsio/services/{service_id} JWT Get a service by ID
PUT /groupsio/services/{service_id} JWT Update a service
DELETE /groupsio/services/{service_id} JWT Delete a service
GET /groupsio/services/_projects JWT List projects that have GroupsIO services
GET /groupsio/services/find_parent?project_uid=<uuid> JWT Find the parent service for a project

GroupsIO Mailing Lists

Method Path Auth Description
GET /groupsio/mailing-lists JWT List mailing lists, filtered by ?project_uid=<uuid> and/or ?committee_uid=<uuid>
POST /groupsio/mailing-lists JWT Create a mailing list
GET /groupsio/mailing-lists/{subgroup_id} JWT Get a mailing list by ID
PUT /groupsio/mailing-lists/{subgroup_id} JWT Update a mailing list
DELETE /groupsio/mailing-lists/{subgroup_id} JWT Delete a mailing list
GET /groupsio/mailing-lists/count?project_uid=<uuid> JWT Get mailing list count for a project
GET /groupsio/mailing-lists/{subgroup_id}/member_count JWT Get member count for a mailing list

GroupsIO Members

Method Path Auth Description
GET /groupsio/mailing-lists/{subgroup_id}/members JWT List members of a mailing list
POST /groupsio/mailing-lists/{subgroup_id}/members JWT Add a member to a mailing list
GET /groupsio/mailing-lists/{subgroup_id}/members/{member_id} JWT Get a member by ID
PUT /groupsio/mailing-lists/{subgroup_id}/members/{member_id} JWT Update a member
DELETE /groupsio/mailing-lists/{subgroup_id}/members/{member_id} JWT Remove a member
POST /groupsio/mailing-lists/{subgroup_id}/invitemembers JWT Invite members by email

GroupsIO Artifacts

Method Path Auth Description
GET /groupsio/mailing-lists/{subgroup_id}/artifacts/{artifact_id} JWT Get artifact metadata
GET /groupsio/mailing-lists/{subgroup_id}/artifacts/{artifact_id}/download JWT Get a presigned S3 download URL (expires in 15 min)

Utilities

Method Path Auth Description
POST /groupsio/checksubscriber JWT Check if an email is subscribed to a mailing list

OpenAPI Specs

Method Path Auth Description
GET /_groupsio/openapi.json None OpenAPI 2.0 (JSON)
GET /_groupsio/openapi3.json None OpenAPI 3.0 (JSON)
GET /_groupsio/openapi.yaml None OpenAPI 2.0 (YAML)
GET /_groupsio/openapi3.yaml None OpenAPI 3.0 (YAML)

Examples

All examples use mock auth. Any non-empty Bearer token is accepted when AUTH_SOURCE=mock.

TOKEN="test-token"
BASE="http://localhost:8080"

Health Checks

curl $BASE/livez
# OK

curl $BASE/readyz
# OK

GroupsIO Services

List services for a project:

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE/groupsio/services?project_uid=<project-uuid>"

Get a service:

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE/groupsio/services/<service-id>"

Find parent service for a project:

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE/groupsio/services/find_parent?project_uid=<project-uuid>"

Create a service:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project_uid":"<uuid>","type":"v2_primary","domain":"groups.io","prefix":"myorg","status":"active"}' \
  "$BASE/groupsio/services"

Update a service:

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"inactive"}' \
  "$BASE/groupsio/services/<service-id>"

Delete a service:

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "$BASE/groupsio/services/<service-id>"
# 204 No Content

GroupsIO Mailing Lists

List mailing lists for a project:

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE/groupsio/mailing-lists?project_uid=<project-uuid>"

List mailing lists for a committee:

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE/groupsio/mailing-lists?committee_uid=<committee-uuid>"

Get a mailing list:

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE/groupsio/mailing-lists/<subgroup-id>"

Get mailing list count for a project:

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE/groupsio/mailing-lists/count?project_uid=<project-uuid>"

Get member count for a mailing list:

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE/groupsio/mailing-lists/<subgroup-id>/member_count"

Create a mailing list:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project_uid":"<uuid>","group_name":"my-list","description":"My list","type":"private","audience_access":"member"}' \
  "$BASE/groupsio/mailing-lists"

Update a mailing list:

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description":"Updated description"}' \
  "$BASE/groupsio/mailing-lists/<subgroup-id>"

Delete a mailing list:

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "$BASE/groupsio/mailing-lists/<subgroup-id>"
# 204 No Content

GroupsIO Members

List members:

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE/groupsio/mailing-lists/<subgroup-id>/members"

Get a member:

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE/groupsio/mailing-lists/<subgroup-id>/members/<member-id>"

Add a member:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@example.com","member_type":"committee"}' \
  "$BASE/groupsio/mailing-lists/<subgroup-id>/members"

Update a member:

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"delivery_mode":"digest"}' \
  "$BASE/groupsio/mailing-lists/<subgroup-id>/members/<member-id>"

Remove a member:

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "$BASE/groupsio/mailing-lists/<subgroup-id>/members/<member-id>"
# 204 No Content

Invite members by email:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"emails":["alice@example.com","bob@example.com"]}' \
  "$BASE/groupsio/mailing-lists/<subgroup-id>/invitemembers"
# 204 No Content

GroupsIO Artifacts

Get artifact metadata:

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE/groupsio/mailing-lists/<subgroup-id>/artifacts/<artifact-uuid>"

Get presigned download URL:

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE/groupsio/mailing-lists/<subgroup-id>/artifacts/<artifact-uuid>/download"
# {"url":"https://s3.amazonaws.com/...?X-Amz-Expires=900&..."}

Check Subscriber

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@example.com","subgroup_id":"<subgroup-id>"}' \
  "$BASE/groupsio/checksubscriber"