API Reference

Warning

This page is still incomplete and considered a stub.

Tip

This page is quite long. As a result, use the 'Pages' table of content on the right to navigate!

The Regreso API is implemented using tRPC. All routers/procedures are accessible either through tRPC or the OpenAPI-compatible REST API (powered by trpc-to-openapi).

OpenAPI/REST Specification

API Endpoint: https://regreso.netlify.app/api OpenAPI Document: http://regreso.netlify.app/api/v1/openapi.json

Versioning:

The Regreso REST API may possess procedure versions to ensure compatibility with outdated versions of clients and extensions. Be careful about using old API versions as old procedure versions may be discontinued at any time if found to be difficult to maintain securely.

Keep in mind:

• All OpenAPI-compatible procedures/routers should be used with Content-Type: application/json.
• Any protected procedure must be accessed using an Authorization header set to the session token.
• Input schemas should be provided through POST/PATCH request bodies
• Unless specified otherwise, update procedures use PATCH requests, create, POST, get{one or many}, GET, and delete, DELETE

Routers

User (user)

Important

This router is not implemented in db, server, or frontend. Follow progress in #111

Session (session)

• session.hello: Protected Query

  A procedure intended for debugging or demonstration of API uptime/function as well as user login status.

  Output Object Schema:

  {
    greeting: String // A string response which says hello with your name!
  }

  REST Specification:

  method: GET
  path: /v1/say-hello

• session.get: Protected Query

  A procedure for retrieving information about the current session. Must be authenticated.

  Output Object Schema:

  {
    id: String, // The session id, or token
    expiresAt: Date, // When this session will become invalid
    user: User // The `User` object associated with the session
  }

  REST Specification:

  method: GET
  path: /v1/session

• session.create: Public Mutation

  A procedure intended for logging into Regreso. Currently, OAuth accounts cannot be logged in-to with the API. Instead, use a user's session token to authenticate requests directly instead.

  Input Object Schema:

  {
    email: String, // A string email address
    password: String, // A string password
  }

  Output Object Schema:

  { 
    success: Boolean, // Whether the creation was successful
    message?: String, // If success is false, the error message to be displayed
    token?: String, // If success is true, the id of the new session
    expiresAt?: Date, // If success is true, when the new session expires
    user?: User //  If success is true, the `User` associated with the new session
  }  

  REST Specification:

  method: POST
  path: /v1/session

• session.delete: Protected Mutation

  A procedure intended for signing out of a Regreso session associated with the authorization header

  Input Object Schema:

  {}

  Output Object Schema:

  { 
    success: Boolean, // Whether the deletion was successful
  }  

  REST Specification:

  method: DELETE
  path: /v1/session

Destination (destination)

• destination.create: Protected Mutation

  A procedure intended for creating a new destination. Must be authenticated.

  Input Object Schema:

  {
    type: "location" | "note" | "file", // The type of destination to be created
    location: String | null, // The location URL for location-type destinations
    name: String, // The destination headline (max length: 100 chars)
    body: String | null, // The destination body content (max length: 1000 chars)
    tags: {
      id: String, // The tag id
      text: // The tag name/display text
    }[], // A list of tags
    workspaceId?: Number // The destination's workspace's ID
  }

  Output Object Schema:

  { 
    success: Boolean, // Whether the creation was successful
  }  

  REST Specification:

  method: POST
  path: /v1/destinations

• destination.getMany: Protected Query

  A procedure for retrieving multiple destinations based on a search query.

  Input Object Schema:

  {
    type?: "location" | "note" | "file", // The type of destination to search
    tags?: String[], // An array of tags' shortcuts or names
    sortBy?: "createAt" | "updatedAt" | "name", // What field to sort results by
    order?: "ASC" | "DESC", // Whether to sort in ascending or descending order
    lists?: Number[], // An array of list IDs that contain results
    searchString?: String, // A text search of destinations by name/body
    location?: String, // A Regular Expression for searching URLs
    limit?: Number, // The number of results to return (max: 30)
    offset?: Number, // Pagination offset
    archived?: Boolean | Null, // Whether to return (True: Archived, False: Unarchived, Null: Both)
    workspaceId?: Number // The destination's workspace's ID
  }

  Output Object Schema:

  import type Destination from "./models";
  {
    items: Destination[], // An array of destinations
    count: Number // The number of destinations returned
  }

  REST Specification:

  method: GET
  path: /v1/destinations

• destination.update: Protected Mutation

  A procedure intended for updating a destination.

  Input Object Schema:

  {
    // Optional: Anything from destination.create in addition to:
    archived?: Boolean // Whether the destination should be archived
  }

  Output Object Schema:

  { 
    success: Boolean, // Whether the update was successful
  }  

  REST Specification:

  method: PATCH
  path: /v1/destination/{id} # where id is a numerical destination id

• destination.get: Protected Query

  A procedure for retrieving information about a single destination.

  Output Object Schema:

  {
    id: Number, // The destination's ID
    userId: Number, // The creator's ID
    createdAt: Date, // When the destination was made
    updatedAt: Date | null, // When the destination was last updated
    tags?: {
      id: String, // The tag id
      text: // The tag name/display text
    }[], // An array of tags
    type: "location" | "note" | "file", // The type of destination
    name: String | null, // The destination's headline
    location: String | null, // The destination's URL location
    body: String | null, // The body content of the destination
    workspace: Workspace, // An object for the destination's workspace,
    archived: Boolean // Whether the destination is archived
  }

  REST Specification:

  method: GET
  path: /v1/destination/{id} # where id is a numerical destination id

• destination.delete: Protected Mutation

  A procedure intended for permanently deleting a Regreso destination.

  Input Object Schema:

  {}

  Output Object Schema:

  { 
    success: Boolean, // Whether the deletion was successful
  }  

  REST Specification:

  method: DELETE
  path: /v1/destination/{id} # where id is a numerical destination id

• destination.addToLists: Protected Mutation

  A procedure intended for adding a destination to list(s)

  Input Object Schema:

  {
    lists: Number[], // An array of list IDs
  }

  Output Object Schema:

  { 
    success: Boolean, // Whether the list addition was successful
  }  

  REST Specification:

  method: POST
  path: /v1/destination/{id}/add-lists # where id is a numerical destination id

• destination.removeFromLists: Protected Mutation

  A procedure intended for removing a destination from list(s)

  Input Object Schema:

  {
    lists: Number[], // An array of list IDs
  }

  Output Object Schema:

  { 
    success: Boolean, // Whether the list removal was successful
  }  

  REST Specification:

  method: POST
  path: /v1/destination/{id}/remove-lists # where id is a numerical destination id

List (list)

Tag (tag)

Workspace (workspace)

Team (team)

Important

This router is not implemented in db, server, or frontend.