Start adding API reference documentation

API.md

@@ -130,3 +130,157 @@ Actions:
 ### web hosting (website / db / FTP account or equivalent)
 
 ...
+
+
+# API Reference
+
+## User endpoints
+
+The following API endpoints invoke operations on an individual
+user. Access is allowed for admins, and for the user itself.
+
+Most requests dealing with encryption keys are so-called *privileged*
+requests, and will require the user's password in the *cur_password*
+parameter in order to decrypt the existing encryption keys.
+
+### `/api/user/get`
+
+Retrieve information about a user and all its associated resources.
+
+Request parameters:
+
+* `username` - user to fetch
+* `sso` - SSO ticket
+
+### `/api/user/change_password`
+
+Change the primary authentication password for a user. This operation
+will update the user's storage encryption keys, or initialize them if
+they do not exist.
+
+Request parameters:
+
+* `username` - name of the user
+* `sso` - SSO ticket
+* `cur_password` - current valid password for the user
+* `password` - new password (unencrypted)
+
+### `/api/user/set_password_recovery_hint`
+
+Sets the secondary authentication password (a hint / response pair,
+used to recover the primary credentials) for a user. This operation
+will update the user's storage encryption keys, or initialize them if
+they do not exist yet.
+
+Request parameters:
+
+* `username` - name of the user
+* `sso` - SSO ticket
+* `cur_password` - current valid password for the user
+* `hint` - the secondary authentication hint
+* `response` - the secondary authentication response (effectively a
+  password, unencrypted)
+
+### `/api/user/enable_otp`
+
+Enable TOTP for a user. The server can generate a new TOTP secret if
+necessary, or it can be generated by the caller (usually better as it
+allows for a better validation UX).
+
+Request parameters:
+
+* `username` - name of the user
+* `sso` - SSO ticket
+* `totp_secret` - new TOTP secret (optional)
+
+### `/api/user/disable_otp`
+
+Disable TOTP for a user. Existing 2FA credentials will be wiped as
+well.
+
+Request parameters:
+
+* `username` - name of the user
+* `sso` - SSO ticket
+
+### `/api/user/create_app_specific_password`
+
+Create a new application-specific password. 2FA must already be
+enabled for the user. A new random password will be generated by the
+server and returned in the response. A new copy of the encryption key
+will be encrypted with the new application-specific password.
+
+ASPs are identified by a unique random ID that is also automatically
+generated by the server.
+
+Request parameters:
+
+* `username` - name of the user
+* `sso` - SSO ticket
+* `cur_password` - current valid password for the user
+* `service` - service that the password should be valid for
+* `notes` - a user-controlled comment about the client
+
+### `/api/user/delete_app_specific_password`
+
+Delete an application-specific password (and the associated encryption
+key).
+
+Request parameters:
+
+* `username` - name of the user
+* `sso` - SSO ticket
+* `asp_id` - ID of the app-specific password
+
+
+## Resource endpoints
+
+These API endpoints manipulate individual resources regardless of
+which user they belong to. Access is normally granted to admins and to
+the user that owns a resource, but some operations are restricted to
+admins only.
+
+### `/api/resource/enable`
+
+Enable a resource (admin-only).
+
+Request parameters:
+
+* `resource_id` - resource ID
+* `sso` - SSO ticket
+* `comment` - notes on the operation
+
+### `/api/resource/disable`
+
+Disable a resource (admin-only).
+
+Request parameters:
+
+* `resource_id` - resource ID
+* `sso` - SSO ticket
+* `comment` - notes on the operation
+
+### `/api/resource/move`
+
+Move a resource between shards (admin-only).
+
+Resources that are part of a group (for instance websites and DAV
+accounts) are moved together, so this request might end up moving more
+than one resource.
+
+Request parameters:
+
+* `resource_id` - resource ID
+* `sso` - SSO ticket
+* `shard` - new shard
+
+### `/api/resource/create`
+
+Create one or more resources associated with a user. Note that if
+creating multiple resources, they must all belong to the same user.
+
+Request parameters:
+
+* `sso` - SSO ticket
+* `resources` - list of resource objects to create
+

actions.go

@@ -321,7 +321,7 @@ func (s *AccountService) disable2FA(ctx context.Context, tx TX, user *User) erro
 type CreateApplicationSpecificPasswordRequest struct {
 	PrivilegedRequestBase
 	Service string `json:"service"`
-	Comment string `json:"comment"`
+	Notes   string `json:"notes"`
 }
 
 // Validate the request.
@@ -354,7 +354,7 @@ func (s *AccountService) CreateApplicationSpecificPassword(ctx context.Context,
 		asp := &AppSpecificPasswordInfo{
 			ID:      randomAppSpecificPasswordID(),
 			Service: req.Service,
-			Comment: req.Comment,
+			Comment: req.Notes,
 		}
 		password := randomAppSpecificPassword()
 		encPass := pwhash.Encrypt(password)

server/server.go

@@ -146,8 +146,8 @@ func (s *AccountServer) Handler() http.Handler {
 	h.HandleFunc("/api/user/set_password_recovery_hint", s.withTx(s.handleSetPasswordRecoveryHint))
 	h.HandleFunc("/api/user/enable_otp", s.withTx(s.handleEnableOTP))
 	h.HandleFunc("/api/user/disable_otp", s.withTx(s.handleDisableOTP))
-	h.HandleFunc("/api/app_specific_password/create", s.withTx(s.handleCreateApplicationSpecificPassword))
-	h.HandleFunc("/api/app_specific_password/delete", s.withTx(s.handleDeleteApplicationSpecificPassword))
+	h.HandleFunc("/api/user/create_app_specific_password", s.withTx(s.handleCreateApplicationSpecificPassword))
+	h.HandleFunc("/api/user/delete_app_specific_password", s.withTx(s.handleDeleteApplicationSpecificPassword))
 	h.HandleFunc("/api/resource/enable", s.withTx(s.handleEnableResource))
 	h.HandleFunc("/api/resource/disable", s.withTx(s.handleDisableResource))
 	h.HandleFunc("/api/resource/create", s.withTx(s.handleCreateResources))