87 lines
2.4 KiB
Plaintext
87 lines
2.4 KiB
Plaintext
syntax = "v1"
|
|
info (
|
|
title: "User service reference"
|
|
version: "1.0.0"
|
|
)
|
|
// Stable public errors are shared by Go code and the API document.
|
|
error (
|
|
Unauthenticated 401 "UNAUTHENTICATED" "authentication required"
|
|
Forbidden 403 "FORBIDDEN" "permission denied"
|
|
UserNotFound 404 "USER_NOT_FOUND" "user not found"
|
|
EmailTaken 409 "EMAIL_TAKEN" "email already in use"
|
|
InvalidUser 400 "INVALID_USER" "invalid user"
|
|
InvalidPage 400 "INVALID_PAGE" "invalid pagination"
|
|
)
|
|
auth AdminAuth (
|
|
type: bearer
|
|
middleware: Auth
|
|
description: "Use an administrator token for writes, or a read-only token for GET requests"
|
|
)
|
|
type (
|
|
UserResp {
|
|
ID int64 `json:"id"`
|
|
Name string `json:"name"`
|
|
Email string `json:"email"`
|
|
CreatedAt string `json:"createdAt"`
|
|
UpdatedAt string `json:"updatedAt"`
|
|
}
|
|
CreateUserReq {
|
|
Name string `json:"name" binding:"required,max=100"`
|
|
Email string `json:"email" binding:"required,email,max=254"`
|
|
}
|
|
UserIDReq {
|
|
ID int64 `path:"id,range=[1:9007199254740991]"`
|
|
}
|
|
UpdateUserReq {
|
|
ID int64 `path:"id,range=[1:9007199254740991]"`
|
|
Name string `json:"name" binding:"required,max=100"`
|
|
Email string `json:"email" binding:"required,email,max=254"`
|
|
}
|
|
ListUsersReq {
|
|
Page int `form:"page,default=1,range=[1:1000000]"`
|
|
PageSize int `form:"pageSize,default=20,range=[1:100]"`
|
|
}
|
|
UserPageResp {
|
|
Items []UserResp `json:"items"`
|
|
Total int `json:"total"`
|
|
Page int `json:"page"`
|
|
PageSize int `json:"pageSize"`
|
|
}
|
|
ExportResp {
|
|
DownloadURL string `json:"downloadUrl"`
|
|
}
|
|
)
|
|
@server (
|
|
group: user
|
|
prefix: /api/v1
|
|
auth: AdminAuth
|
|
errors: Unauthenticated
|
|
)
|
|
service user-api {
|
|
@doc (
|
|
summary: "Create a user"
|
|
description: "Normalizes the email, then commits user data and audit in one transaction"
|
|
tags: users
|
|
)
|
|
@errors Forbidden, InvalidUser, EmailTaken
|
|
@handler createUser
|
|
@status 201
|
|
post /users (CreateUserReq) returns (UserResp)
|
|
@errors UserNotFound
|
|
@handler getUser
|
|
get /users/:id (UserIDReq) returns (UserResp)
|
|
@errors InvalidPage
|
|
@handler listUsers
|
|
get /users (ListUsersReq) returns (UserPageResp)
|
|
@errors Forbidden, InvalidUser, UserNotFound, EmailTaken
|
|
@handler updateUser
|
|
put /users/:id (UpdateUserReq) returns (UserResp)
|
|
@errors Forbidden, UserNotFound
|
|
@handler deleteUser
|
|
delete /users/:id (UserIDReq)
|
|
@doc "Export one user as a private text object with a short-lived download link"
|
|
@errors Forbidden, UserNotFound
|
|
@handler exportUser
|
|
post /users/:id/export (UserIDReq) returns (ExportResp)
|
|
}
|