Repo API

Table of Contents

Site admins use the Repo API to create and manage repos.

import json, requests

api_root = "https://www.instabase.com/api/v1/repos"

See Instabase API authorization and response conventions for authorization and error convention details.

Create a Subspace

Use this API to create a Subspace. This API can be invoked only by:

A site admin
A Space manager

Request

headers = {'Authorization': 'Bearer {0}'.format(token)}
args = {
  'description': 'some description for the repo',
  'visibility': 'public',
}
data = json.dumps(args)
resp = requests.post(api_root + '/<repo_owner>/<repo_name>', headers=headers, data=data).json()

JSON arguments must define the description and visibility of the Subspace:

description: A user-friendly description of the Subspace.
visibility: Specify public or private visibility.

A repo_owner/repo_name uniquely identifies a repo, meaning a user (or an Organization) cannot contain two repos with the same name.

Specify the repo name in the API route, where it is:

composed only of alphanumeric characters, underscores, and hyphens

Get Subspace information

Use this API to retrieve Subspace information.

This API can be invoked only by:

A site admin
A Space manager for this Subspace
Anyone who has been granted permission to access the Subspace.

Request

headers = {'Authorization': 'Bearer {0}'.format(token)}
resp = requests.get(api_root + '/<repo_owner>/<repo_name>', headers=headers).json()

Response

The response includes the owner, the visibility (public or private), the user collaborators, and team collaborators.

If successful:

{
  "status": "OK",
  "repo": {
    "owner": "user1",
    "name": "repo1",
    "description": "description for repo1",
    "visibility": "private",
    "members": {
      "accessor": [
        {
          "type": "user",
          "name": "bob"
        },
        {
          "type": "group",
          "name": "testers"
        }
      ],
      "admin": [
        {
          "type": "user",
          "name": "alice"
        }
      ],
      "collaborator": [
        {
          "type": "group",
          "name": "sales"
        }
      ]
    }
  }
}

Update Subspace

Use this API to update the Subspace name, visibility, description, or transfer ownership of the Subspace to another Space.

This API can be invoked by:

A site admin
A Space manager for this Subspace
A user who is a Subspace manager on this Subspace

Request

headers = {'Authorization': 'Bearer {0}'.format(token)}
args = {
  'name': 'new-repo-name',
  'visibility': 'public',
  'description': 'new_description',
  'owner': 'new-repo-owner'
}
data = json.dumps(args)
resp = requests.patch(api_root + '/<repo_owner>/<repo_name>', headers=headers, data=data).json()

At least one of the three fields must be provided.

Response

If not successful, more details are provided in error_details with a JSON dictionary that identifies the reason and description of the failed updates.

{
  "status": "ERROR",
  "msg": "Update failed",
  "error_details": {
    "AUTHENTICATION": "Failed to find or access the repo",
    "RENAME": "Why the repo failed to be renamed",
    "CHANGE_VISIBILITY": "Why the visibility was not updated",
    "DESCRIPTION": "Why the description was not updated",
  }
}

Delete Subspace

Use this API to delete a Subspace.

This API can be invoked only by:

A site admin
A Space manager for this Subspace
A user who is a Subspace manager on this Subspace

Request

headers = {'Authorization': 'Bearer {0}'.format(token)}
resp = requests.delete(api_root + '/<repo_owner>/<repo_name>', headers=headers).json()

Add/Remove users to Subspace

Use this API to grant users or groups different roles on the Subspace. The supported roles are admin and collaborator.

This API can be invoked only by:

A site admin
A Space manager for this Subspace
A user who is a Subspace manager on this Subspace

Request

headers = {'Authorization': 'Bearer {0}'.format(token)}
args = {
  'perms':{
    'collaborator': {
      'users': {
        'user1': False,
        'user2': True
      },
      'groups': {
        'group1': False,
        'group2': True
      }
    },
    'admin': {
      'users': {
        'user2': False,
        'user3': True
      },
      'groups': {
        'testgroup2': False,
        'testgroup3': True
      }
    }
  }
}
data = json.dumps(args)
resp = requests.post(api_root + '/<repo_owner>/<repo_name>/members', headers=headers, data=data).json()

Response

If not successful, more details are provided in error_details with a JSON dictionary that identifies the reasons and descriptions of the failed updates.

{
  "status": "ERROR",
  "msg": "Failed to update all repo roles.",
  "error_details": {
    "users": {
      "user1": "User (user1) not found",
      "user2": "User (user2) not found"
    },
    "groups": {
      "group3": "Group (group3) not found"
    }
  }
}

Add custom ACLs for a user or group

Use this API to grant users or groups custom fine-grained ACLs to different resources within a subspace. Setting some ACLs for a resource will not overwrite other existing ACLs for that resource and will also not overwrite ACLs for other resources.

This API can be invoked only by:

A site admin
A Space manager for this Subspace
A user who is a Subspace manager on this Subspace

Request

headers = {'Authorization': 'Bearer {0}'.format(token)}
args = {
  "principal_type": "user",
  "principal_name": "alice",
  "is_delete": false,
  "app_resources": {
    "ib_flow": {
      "web:read": true,
      "web:write": false
    },
      "ib_texteditor": {
        "web:read": false
    }
  },
  "fs_resources": {
    "Instabase Drive": {
      "/": {
        "fs:read": true,
        "fs:write": false
      }
    }
  }
}
data = json.dumps(args)
resp = requests.post(api_root + '/<repo_owner>/<repo_name>/acl/principal', headers=headers, data=data).json()

Response

If not successful, more details are provided in error_details with a JSON dictionary that identifies the reasons and descriptions of the failed updates.

{
  "status": "ERROR",
  "app_errors": {
    "ib_flow": "Invalid ib_flow action."
  },
  "fs_errors": {
    "Instabase Drive": "Invalid file-system drive."
  }
}

List Subspaces in Space

Use this API to retrieve a list of all Subspaces (Repos) within a Space. This API can be invoked by all, but the returned list will only contain Subspaces the requesting user has permissions to access.

Request

Supported query parameters are:

app_id: (Optional) If an Application name is specified, the list returned includes Subspaces only where the requesting user has permissions to use the Application.

headers = {'Authorization': 'Bearer {0}'.format(token)}
resp = requests.get(api_root + '/<repo_owner>?app_id=ib_texteditor', headers=headers).json()

Response

If successful:

{
    "status": "OK",
    "repos": [
        {
            "owner": "ib_eng_space",
            "name": "Engineering repo",
            "description": "Instabase Engineering",
            "is_admin": true,
            "is_collaborator": false,
            "visibility": "private",
            "app_actions": {
              "ib_texteditor": {
                "web:read": true,
                "web:write": true
              }
            }
        },
        {
            "owner": "ib_eng_space",
            "name": "Testing repo",
            "description": "Instabase QA",
            "is_admin": true,
            "is_collaborator": true,
            "visibility": "public",
            "app_actions": {
              "ib_texteditor": {
                "web:read": true
              }
            }
        }
    ]
}

The body of the response is a JSON dictionary with the following fields:

repos: The list of Subspaces (Repos) and their metadata

Each Subspace (Repo) in the repos list contains:

owner: The unique repo_owner of the Space.
name: The name of the Subspace (Repo).
description: The Subspace description.
is_admin: Indicates whether the requesting user is an admin of the Subspace.
is_collaborator: Indicates whether the requesting user is a collaorator on the Subspace.
visibility: The visibility of the Repo, valid values are public and private.
app_actions: Only returned if an app_id is specified in the request. This returns the list of permissions the user has on the specified Application within the Subspace.

List Subspace ACL Resources

Use this API to retrieve a list of all supported Resource names that custom ACLs can be applied to. The list will include all Applications and File-system drive names.

This API can be invoked only by:

A site admin
A Space manager for this Subspace
Anyone who has been granted permission to access the Subspace.

Request

headers = {'Authorization': 'Bearer {0}'.format(token)}
resp = requests.get(api_root + '/repos/<repo_owner>/<repo_name>/list_resources', headers=headers).json()

Response

If successful:

{
    "status": "OK",
    "app_names": [
      "ib_classifier",
      "ib_diffchecker",
      "ib_flow",
      "ib_texteditor"
    ],
    "fs_names": [
      "Instabase Drive",
      "NFS Drive"
    ]
}

The body of the response is a JSON dictionary with the following fields:

app_names: The list app names
fs_names: The list of file-system drive names

List Subspace ACLs for Resource

Use this API to retrieve the list of users and groups that have each ACL for this resource. A resource can be an application or a file system drive name.

This API can be invoked only by:

A site admin
A Space manager for this Subspace
Anyone who has been granted permission to access the Subspace.

Request

headers = {'Authorization': 'Bearer {0}'.format(token)}

# Use the app_id query parameter for an Application Resource
# Use the fs_id query parameter for a File-system drive Resource
resp = requests.get(api_root + '/repos/<repo_owner>/<repo_name>/acl/resource?fs_id=Instabase%20Drive', headers=headers).json()

Response

If successful:

{
    "status": "OK",
    "perms": [
      {
        "actions": {
          "fs:delete": {
            "users": [],
            "groups": []
          },
          "fs:read": {
            "users": ["alice"],
            "groups": []
          },
          "fs:write": {
            "users": [],
            "groups": []
          }
        },
        "path": "/"
      }
    ]
}

The body of the response is a JSON dictionary with the following fields:

perms: The list of ACLs for this resource