History

Márton Elek 96b88e286e build: fix conditional run of web builds Jenkins doesn't do a very good job with identifying what has been changed. While it has a syntax to defined patterns, it compares the current build with the previous build (in case of git-verify it can be a totally different branch) instead of checking the HEAD commit. This patch introduces shell scripts to do this better: * It doesn't depend on Jenkins any more * It can be executed locally * It can detect web changes properly (see the relation change as an example). Change-Id: I9d37775e3818c08c4aa96ffb78f84d57f28a2c95		2022-08-11 14:34:44 +00:00
..
ui	build: fix conditional run of web builds	2022-08-11 14:34:44 +00:00
apikeys_test.go	satellite/admin: Response 404 when entity not found	2021-10-07 12:42:25 +02:00
apikeys.go	satellite/admin: Move declaration before first usage	2021-10-24 18:38:41 +02:00
bucket_test.go	satellite/admin: Move geofence endpoint to bucket info	2021-11-30 18:47:14 +01:00
bucket_testplanet_test.go	satellite/admin: Move geofence endpoint to bucket info	2021-11-30 18:47:14 +01:00
bucket.go	satellite/admin: update geofence endpoints to follow response conventions	2022-01-13 12:33:10 -06:00
common.go	satellite/admin: Use helper for sending JSON	2021-10-04 12:13:04 +02:00
oauthclients_testplanet_test.go	all: fix linting issues	2022-03-21 15:26:42 +00:00
oauthclients.go	satellite/oidc: move oidc into common package	2022-02-08 09:46:54 -06:00
project_test.go	satellite/{console,satellitedb}: add PublicID to Project, db method GetByPublicID	2022-07-21 19:49:26 +00:00
project.go	satellite/admin: allow deletion of paid tier user projects when invoiced	2022-05-30 13:54:51 +02:00
README.md	satellite/admin: allow disabling of MFA	2022-05-30 13:56:11 +02:00
restkeys_test.go	satellite: Rename "acct mgmt api" to "rest api"	2022-04-25 18:51:46 +00:00
restkeys.go	satellite: Rename "acct mgmt api" to "rest api"	2022-04-25 18:51:46 +00:00
server_test.go	satellite/admin/ui,web/{multinode,storagenode}: build without embedding	2022-03-29 13:18:04 +03:00
server.go	satellite/admin: allow disabling of MFA	2022-05-30 13:56:11 +02:00
testutils_test.go	satellite/admin: Send JSON content-type for errors	2021-10-04 12:13:04 +02:00
user_test.go	satellite/console: use new type UpdateUserRequest as arg to db users.Update	2022-06-14 09:28:03 -04:00
user.go	satellite/admin: return only owned projects for get user endpoint	2022-06-22 13:09:36 +03:00

README.md

satellite/admin

Satellite Admin package provides API endpoints for administrative tasks.

Requires setting Authorization header for requests.

satellite/admin
- API design
  - Successful responses
  - Error responses
- API Endpoints

API design

Successful responses

For non-get requests (PUT, POST, DELETE), endpoints should return an empty response body on success. GET requests can return a non-empty body for the resource that we're interacting with.

Error responses

When an API endpoint returns a client error (status code 4XX) it returns a JSON error response which contains 2 fields:

error: The error message.
detail (may be empty): Some detail about the returned error.

Example:

{
  "error": "usage for the current month exists",
  "detail": ""
}

API Endpoints

User Management

POST /api/users

Adds a new user.

An example of a required request body:

{
    "email": "alice@mail.test",
    "fullName": "Alice Test",
    "password": "password"
}

A successful response body:

{
    "id":           "12345678-1234-1234-1234-123456789abc",
    "email":        "alice@mail.test",
    "fullName":     "Alice Test",
    "shortName":    "",
    "passwordHash": ""
}

PUT /api/users/{user-email}

Updates the details of existing user found by its email.

Some example request bodies:

{
    "email": "alice+2@mail.test"
}

{
    "email": "alice+2@mail.test",
    "shortName": "myNickName"
}

{
    "projectLimit": 200
}

GET /api/users/{user-email}

This endpoint returns information about user and their projects.

A successful response body:

{
    "user":{
        "id": "12345678-1234-1234-1234-123456789abc",
        "fullName": "Alice Bob",
        "email":"alice@example.test",
        "projectLimit": 10
    },
    "projects":[
        {
            "id": "abcabcab-1234-abcd-abcd-abecdefedcab",
            "name": "Project",
            "description": "Project to store data.",
            "ownerId": "12345678-1234-1234-1234-123456789abc"
        }
    ]
}

DELETE /api/users/{user-email}

Deletes the user.

DELETE /api/users/{user-email}/mfa

Disables the user's mfa.

OAuth Client Management

Manages oauth clients known to the Satellite.

POST /api/oauth/clients

Create a new OAuthClient. A client ID and clientSecret will be returned upon creation.

Example request:

{
  "id": "uuid-of-the-client",
  "secret": "shh-this-should-be-kept-safe",
  "redirectURL": "http://localhost:8888/oauth/storj/callback",
  "userID": "uuid-of-the-owner",
  "appName": "Example App",
  "appLogoURL": "http://localhost:8888/logo.png"
}

PUT /api/oauth/clients/{id}

Update an existing oauth client.

Example request:

{
  "redirectURL": "http://localhost:8888/oauth/storj/callback",
  "appName": "Example App",
  "appLogoURL": "http://localhost:8888/logo.png"
}

DELETE /api/oauth/clients/{id}

Delete the identified oauth client.

Project Management

POST /api/projects

Adds a project for specific user.

An example of a required request body:

{
    "ownerId": "ca7aa0fb-442a-4d4e-aa36-a49abddae837",
    "projectName": "My Second Project"
}

A successful response body:

{
    "projectId": "ca7aa0fb-442a-4d4e-aa36-a49abddae646"
}

GET /api/projects/{project-id}

Gets the common information about a project.

PUT /api/projects/{project-id}

Updates project name or description.

{
    "projectName": "My new Project Name",
    "description": "My new awesome description!"
}

DELETE /api/projects/{project-id}

Deletes the project.

GET /api/projects/{project}/apikeys

Get the list of the API keys of a specific project.

A successful response body:

[
    {
        "id": "b6988bd2-8d21-4bee-91ac-a3445bf38180",
        "ownerId": "ca7aa0fb-442a-4d4e-aa36-a49abddae837",
        "name": "mine",
        "partnerID": "a9d3b7ee-17da-4848-bb0e-1f64cf45af18",
        "createdAt": "2020-05-19T00:34:13.265761+02:00"
    },
    {
        "id": "f9f887c1-b178-4eb8-b669-14379c5a97ca",
        "ownerId": "3eb45ae9-822a-470e-a51a-9144dedda63e",
        "name": "family",
        "partnerID": "",
        "createdAt": "2020-02-20T15:34:24.265761+02:00"
    }
]

POST /api/projects/{project}/apikeys

Adds an apikey for specific project.

An example of a required request body:

{
    "name": "My first API Key"
}

Note: Additionally you can specify partnerId to associate it with the given apikey. If you specify it, it has to be a valid uuid and not an empty string.

A successful response body:

{
    "apikey": "13YqdMKxAVBamFsS6Mj3sCQ35HySoA254xmXCCQGJqffLnqrBaQDoTcCiCfbkaFPNewHT79rrFC5XRm4Z2PENtRSBDVNz8zcjS28W5v"
}

DELETE /api/projects/{project}/apikeys/{name}

Deletes the given apikey by its name.

GET /api/projects/{project-id}/usage

This endpoint returns whether the project has outstanding usage or not.

A project with not usage returns status code 200 and {"result":"no project usage exist"}. Otherwise, it returns status code 409 with a JSON error.{"error":"usage for current month exists""}.

GET /api/projects/{project-id}/limit

This endpoint returns information about project limits.

A successful response body:

{
  "usage": {
    "amount": "1.0 TB",
    "bytes": 1000000000000
  },
  "bandwidth": {
    "amount": "1.0 TB",
    "bytes": 1000000000000
  },
  "rate": {
    "rps": 0
  },
  "maxBuckets": 1000,
  "maxSegments": 1000000000
}

Update limits

You can update the different limits with one single request just adding the various query parameters (e.g. usage=5000000&bandwidth=9000000)

POST /api/projects/{project-id}/limit?usage={value}

Updates usage limit for a project. The value must be in bytes.

POST /api/projects/{project-id}/limit?bandwidth={value}

Updates bandwidth limit for a project. The value must be in bytes.

POST /api/projects/{project-id}/limit?rate={value}

Updates rate limit for a project.

POST /api/projects/{project-id}/limit?buckets={value}

Updates number of buckets limit for a project.

POST /api/projects/{project-id}/limit?burst={value}

Updates burst limit for a project.

POST /api/projects/{project-id}/limit?segments={value}

Updates number of segments limit for a project.

Bucket Management

This set of APIs provide administrative functionality over bucket functionality.

GET /api/projects/{project-id}/buckets/{bucket-name}

Returns all the information of the specified bucket.

Geofencing

Manage geofencing capabilities for a given bucket.

POST /api/projects/{project-id}/buckets/{bucket-name}/geofence?region={value}

Enables the geofencing configuration for the specified bucket. The bucket MUST be empty in order for this to work. Valid values for the region parameter are:

EU - restrict placement to data nodes that reside in the European Union
EEA - restrict placement to data nodes that reside in the European Economic Area
US - restricts placement to data nodes in the United States
DE - restricts placement to data nodes in Germany

DELETE /api/projects/{project-id}/buckets/{bucket-name}/geofence

Removes the geofencing configuration for the specified bucket. The bucket MUST be empty in order for this to work.

APIKey Management

DELETE /api/apikeys/{apikey}

Deletes the given apikey.