JakeHillion/storj
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ba009b846f
storj/satellite/admin
History
Egon Elbre 15dc797efd web/{multinode,satellite,storagenode}: revert go.mod 
Adding go.mod into node_modules is not sufficient, because npm install
wipes them quite often out. Similarly, when running npm install locally
it will remove it, causing the git state to be dirty.

Rather than having them committed, add them after running npm install.

Change-Id: Iaf21a9c6e198dc31fe50345ec5dee85b44617176
2022-07-08 19:51:51 +03:00
..
ui web/{multinode,satellite,storagenode}: revert go.mod 2022-07-08 19:51:51 +03: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/{payments/storjscan,satellitedb}: Add wallet implementation 2022-06-03 11:45:47 +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.

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.