Skip to content

Latest commit

 

History

History
358 lines (269 loc) · 8.07 KB

api.md

File metadata and controls

358 lines (269 loc) · 8.07 KB
Raw

Embrasure API Documentation

This documentation provides information on the RESTful API endpoints for managing secrets and users with the Embrasure Secrets API. Secrets are key-value pairs stored in a database, and users have permissions for accessing and managing secrets.

Table of Contents

Introduction

This API allows you to interact with secrets and users, providing CRUD (Create, Read, Update, Delete) operations for managing key-value pairs and user permissions.

Base URLs:

  • Secrets: /secrets
  • Users: /users

Authentication

The Embrasure API requires authentication via request headers. You should include the following headers in your requests:

  • db-username: Your database username.
  • db-auth-token: Your database authentication token.
  • db-name: The name of the database.
  • db-host: The database host URL.
  • db-port: The database port.

Secrets API

Get All Secrets

  • Endpoint: GET /secrets
  • Description: Retrieve a list of all secrets.
  • Responses:
    • 200 OK: Successfully retrieved the list of secrets.
    • 500 Internal Server Error: An error occurred on the server.

Example Request:

GET /secrets

Example Response (200 OK):

[
    {
        "key": "spotify",
        "value": "asdv234asdv4"
    },
    {
        "key": "github",
        "value": "ac!@#$WDSca"
    }
]

Get a Single Secret

  • Endpoint: GET /secrets/:key
  • Description: Retrieve a single secret by providing its key.
  • Request Parameters:
    • key: The key of the secret to retrieve.
  • Responses:
    • 200 OK: Successfully retrieved the secret. Returns the secret data.
    • 404 Not Found: Secret with the provided key does not exist.
    • 500 Internal Server Error: An error occurred on the server.

Example Request:

GET /secrets/mySecretKey

Example Response (200 OK):

{
    "key": "mySecretKey",
    "value": "My Secret Value"
}

Delete a Single Secret

  • Endpoint: DELETE /secrets/:key
  • Description: Delete a secret by providing its key.
  • Request Parameters:
    • key: The key of the secret to retrieve.
  • Responses:
    • 204 No Content: Secret successfully deleted.
    • 404 Not Found: Secret with the provided key does not exist.
    • 500 Internal Server Error: An error occurred on the server.

Example Request:

DELETE /secrets/mySecretKey

Example Response (204 No Content):

No content in the response body.

Update a Secret

  • Endpoint: PATCH /secrets/:key
  • Description: Update the value of a secret by providing its key.
  • Request Parameters:
    • key: The key of the secret to retrieve.
  • Request Body:
    • value: The new value for the secret.
  • Responses:
    • 204 No Content: Secret successfully updated.
    • 404 Not Found: Secret with the provided key does not exist.
    • 500 Internal Server Error: An error occurred on the server.

Example Request:

PATCH /secrets/mySecretKey

Example Request Body:

{
    "value": "Updated Value"
}

Example Response (204 No Content):

No content in the response body.

Create a Secret

  • Endpoint: POST /secrets
  • Description: Create a new secret.
  • Request Body:
    • key: The key of the new secret.
    • value: The new value for the secret.
  • Responses:
    • 201 Created: Secret successfully created. Returns the key of the created secret.
    • 500 Internal Server Error: An error occurred on the server.

Example Request:

POST /secrets

Example Request Body:

{
    "key": "NewSecretKey",
    "value": "New Secret Value"
}

Example Response (201 Created):

{
    "key": "NewSecretKey"
}

Users API

Get All Users

  • Endpoint: GET /users
  • Description: Retrieve a list of all users.
  • Responses:
    • 200 OK: Successfully retrieved the list of users.
    • 500 Internal Server Error: An error occurred on the server.

Example Request:

GET /users

Example Response (200 OK):

[
    {
        "username": "johndoe",
        "hasWritePermissions": true
    },
    {
        "username": "janedoe",
        "hasWritePermissions": false
    }
]

Get User Permissions

  • Endpoint: GET /users/:username
  • Description: Retrieve a user's permissions by providing their username.
  • Request Parameters:
    • username: The username of the user to retrieve permissions for.
  • Responses:
    • 200 OK: Successfully retrieved the user's permissions. Returns an array of permissions.
    • 404 Not Found: User with the provided username does not exist.
    • 500 Internal Server Error: An error occurred on the server.

Example Request:

GET /users/johndoe

Example Response (200 OK):

["SELECT"]

Delete user

  • Endpoint: DELETE /users/:username
  • **Description:**Delete a user by providing their username.
  • Request Parameters:
    • username: The username of the user to delete.
  • Responses:
    • 204 No Content: User successfully deleted.
    • 404 Not Found: User with the provided username does not exist.
    • 500 Internal Server Error: An error occurred on the server.

Example Request:

DELETE /users/johndoe

Example Response (204 No Content):

No content in the response body.

Edit User Permissions

  • Endpoint: PUT /users/:username
  • Description: Edit a user's read/write permission by providing their username.
  • Request Parameters:
    • setWritePermissionTo: A boolean indicating whether to set the write permission to true or false.
  • Responses:
    • 200 OK: User's permission successfully updated. Returns the updated user data.
    • 404 Not Found: User with the provided username does not exist.
    • 500 Internal Server Error: An error occurred on the server.

Example Request:

PUT /users/johndoe

Example Request Body:

{
    "setWritePermissionTo": true
}

Example Response (200 OK):

{ "writePermission": true }

Create User

  • Endpoint: POST /users

  • Description: Create a new user.

  • Request Body:

    • username: The username of the new user.
    • hasWritePermissions: A boolean indicating whether the user has write permissions.

  • Responses:

    • 201 Created: User successfully created. Returns the username of the created user.
    • 500 Internal Server Error: An error occurred on the server.

Example Request:

POST /users

Example Request Body:

{
    "username": "newuser",
    "hasWritePermissions": true
}

Example Response (201 Created):

{
    "username": "newuser"
}

Logs API

Get All Logs

  • Endpoint: GET /logs
  • Description: Retrieve a list of all logs.
  • Responses:
    • 200 OK: Successfully retrieved the list of logs.
    • 500 Internal Server Error: An error occurred on the server.

Example Request:

GET /logs

Example Response (200 OK):

[
    {
        "actor": "bob",
        "ip_address": "196.20.24.250",
        "request_type": "GET",
        "resource_route": "secrets",
        "is_request_authenticated": true,
        "is_request_authorized": true,
        "http_status_code": 200,
        "timestamp": 1701201784078
    }
]