Bibliotheca Gateway API API Reference

Bibliotheca Gateway service is responsible for communication between all application microservices. Also it's main API endpoint for Bibliotheca clients such as Bibliotheca.Client (Angular SPA) or custom scripts.

Terms of Service: None
Version: v1

Authentication

apiKey

name
Authorization
in
header
description

As a authorization header you can send one of the following token:
- Bearer - JWT token obtained by OAuth2 authorization
- SecureToken - global token defined as a variable in services parameters
- UserToken - token generated on user property page
- ProjectToken - token generated on project property page

Branches

Branches

Get all branches for specific project.

GET /api/projects/{projectId}/branches

Endpoint returns all branches for specific project.

projectId

Project id.

type
string
in
path
200 OK
ExtendedBranchDto

Branches returned successfully.

400 Bad Request

Request cannot be proceeded..

404 Not Found

Project not exists.

500 Internal Server Error

Internal server error.

Response Example (200 OK) 
[
  {
    "siteName": "string",
    "docsDir": "string",
    "name": "string",
    "mkDocsYaml": "string"
  }
]
Branches

Create a new branch.

POST /api/projects/{projectId}/branches

Endpoint for creating a new branch in project. Information about branch should be send as a JSON in body request.

BranchDto

Information about branch.

projectId

Project id.

type
string
in
path
Request Example
{
  "name": "string",
  "mkDocsYaml": "string"
}
201 Created

Success

Branches

Get information about specific branch in project.

GET /api/projects/{projectId}/branches/{branchName}

Endpoint returns information about one specific project.

projectId

Project id.

type
string
in
path
branchName

Branch name.

type
string
in
path
200 OK
ExtendedBranchDto

Success

Response Example (200 OK) 
{
  "siteName": "string",
  "docsDir": "string",
  "name": "string",
  "mkDocsYaml": "string"
}
Branches

Update information about branch.

PUT /api/projects/{projectId}/branches/{branchName}

Endpoint for updating information about branch. Information about branch should be send as a JSON in body request.

BranchDto

Information about branch.

projectId

Project id.

type
string
in
path
branchName

Branch name.

type
string
in
path
Request Example
{
  "name": "string",
  "mkDocsYaml": "string"
}
200 OK

Success

Branches

Delete specific branch.

DELETE /api/projects/{projectId}/branches/{branchName}

Endpoint for deleting specific branch. Besides branch information endpoint deletes also documentation file stored in branch and index from search service.

projectId

Project id.

type
string
in
path
branchName

Branch name.

type
string
in
path
200 OK

Success

Documents

Documents

Get list of documents from branch in project.

GET /api/projects/{projectId}/branches/{branchName}/documents

Endpoint which returns list of documents from specifuc branch in project. Each object contains base information about document.

projectId

Project id.

type
string
in
path
branchName

Branch name.

type
string
in
path
200 OK
BaseDocumentDto

Success

Response Example (200 OK) 
[
  {
    "uri": "string",
    "name": "string",
    "conentType": "string"
  }
]
Documents

Update all documentation file (form).

PUT /api/projects/{projectId}/branches/{branchName}/documents

Endpoint which is used to send all documentation to specific branch. Current documentation files are deleted and new files are stored instead of them. Compressed file should have one root folder which name is the name of the branch. Compressed file should be send as a part of HTML form in field: "file".

After updating documentation files reindex is executed automatically (if you have search service enabled).

projectId

Project id.

type
string
in
path
branchName

Branch name.

type
string
in
path
ContentType

(no description)

type
string
in
query
ContentDisposition

(no description)

type
string
in
query
Headers

(no description)

type
object
in
query
Length

(no description)

type
integer (int64)
in
query
Name

(no description)

type
string
in
query
FileName

(no description)

type
string
in
query
200 OK

Success

Documents

Create new document information.

POST /api/projects/{projectId}/branches/{branchName}/documents

Endpoint which is used to add a new documentation file to branch in project. Documentation files can be send one by one using this endpoint. However after sending all of the documentation files reindex have to be run manually (if search service is enabled).

DocumentDto

Document data.

projectId

Project id.

type
string
in
path
branchName

Branch name.

type
string
in
path
Request Example
{
  "content": "string (byte)",
  "uri": "string",
  "name": "string",
  "conentType": "string"
}
201 Created

Success

Documents

Get information about specific document.

GET /api/projects/{projectId}/branches/{branchName}/documents/{fileUri}

Endpoint returns detailed information about document. Contains also document body as a JSON property.

projectId

Project id.

type
string
in
path
branchName

Branch name.

type
string
in
path
fileUri

File uri. As a path separator to file is used ":". For example path "docs/folder/index.md" should be converted to "docs:folder:index.md".

type
string
in
path
200 OK
DocumentDto

Success

Response Example (200 OK) 
{
  "content": "string (byte)",
  "uri": "string",
  "name": "string",
  "conentType": "string"
}
Documents

Update documentation information.

PUT /api/projects/{projectId}/branches/{branchName}/documents/{fileUri}

Endpoint which is used to update documentation file in branch in project. After updating documentation data reindex have to be run manually (if search service is enabled).

DocumentDto

Document data.

projectId

Project id.

type
string
in
path
branchName

Branch name.

type
string
in
path
fileUri

File uri. As a path separator to file is used ":". For example path "docs/folder/index.md" should be converted to "docs:folder:index.md".

type
string
in
path
Request Example
{
  "content": "string (byte)",
  "uri": "string",
  "name": "string",
  "conentType": "string"
}
200 OK

Success

Documents

Delete documentation file.

DELETE /api/projects/{projectId}/branches/{branchName}/documents/{fileUri}

Endpoint which is used to delete specific documentation file. After deleting documentation file reindex have to be run manually (if search service is enabled).

projectId

Project id.

type
string
in
path
branchName

Branch name.

type
string
in
path
fileUri

File uri. As a path separator to file is used ":". For example path "docs/folder/index.md" should be converted to "docs:folder:index.md".

type
string
in
path
200 OK

Success

Documents

Get document content.

GET /api/projects/{projectId}/branches/{branchName}/documents/content/{fileUri}

Endpoint returns document content. Markdown files are converted to HTML and returned as a HTML files. Response returns specific file and proper content type based on requested file.

projectId

Project id.

type
string
in
path
branchName

Branch name.

type
string
in
path
fileUri

File uri. As a path separator to file is used ":". For example path "docs/folder/index.md" should be converted to "docs:folder:index.md".

type
string
in
path
200 OK
FileContentResult

Success

Response Example (200 OK) 
{
  "fileContents": "string (byte)",
  "contentType": "string",
  "fileDownloadName": "string"
}
Documents

Update all documentation file (body).

PUT /api/projects/{projectId}/branches/{branchName}/documents/filebody

Endpoint which is used to send all documentation to specific branch. Current documentation files are deleted and new files are stored instead of them. Compressed file should have one root folder which name is the name of the branch. Compressed file should be send as request body.

After updating documentation files reindex is executed automatically (if you have search service enabled).

projectId

Project id.

type
string
in
path
branchName

Branch name.

type
string
in
path
200 OK

Success

Groups

Groups

Get all groups.

GET /api/groups

Endpoint returns all groups which are defined in all documentation projects.

200 OK

Success

Response Example (200 OK) 
[
  "string"
]

Health

Health

Get information about health.

GET /api/health

Endpoint returns simple message when service is alive and reachable. It's used by service discovery to preapare information about service health.

200 OK

Success

Response Example (200 OK) 
"string"

Projects

Projects

Get list of projects.

GET /api/projects

Endpoint returns projects stored in the system.

Groups

(no description)

format
multiple parameters (Groups=aaa&Groups=bbb)
type
string[]
in
query
Tags

(no description)

format
multiple parameters (Tags=aaa&Tags=bbb)
type
string[]
in
query
Query

(no description)

type
string
in
query
Page

(no description)

type
integer (int32)
in
query
Limit

(no description)

type
integer (int32)
in
query
200 OK
FilteredResutsDto[ProjectDto]

Success

Response Example (200 OK) 
{
  "results": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "defaultBranch": "string",
      "visibleBranches": [
        "string"
      ],
      "tags": [
        "string"
      ],
      "group": "string",
      "projectSite": "string",
      "contactPeople": [
        {
          "name": "string",
          "email": "string"
        }
      ],
      "editLinks": [
        {
          "branchName": "string",
          "link": "string"
        }
      ],
      "accessToken": "string",
      "isAccessLimited": "boolean"
    }
  ],
  "allResults": "integer (int32)"
}
Projects

Create a new project.

POST /api/projects

Endpoint for creating a new project. Project is automatically assigned to the user (if authorization service is enabled).

ProjectDto

Project information.

Request Example
{
  "id": "string",
  "name": "string",
  "description": "string",
  "defaultBranch": "string",
  "visibleBranches": [
    "string"
  ],
  "tags": [
    "string"
  ],
  "group": "string",
  "projectSite": "string",
  "contactPeople": [
    {
      "name": "string",
      "email": "string"
    }
  ],
  "editLinks": [
    {
      "branchName": "string",
      "link": "string"
    }
  ],
  "accessToken": "string",
  "isAccessLimited": "boolean"
}
201 Created

Success

Projects

Get specific project.

GET /api/projects/{projectId}

Endpoint returns detailed information about specific project.

projectId

Project id.

type
string
in
path
200 OK
ProjectDto

Success

Response Example (200 OK) 
{
  "id": "string",
  "name": "string",
  "description": "string",
  "defaultBranch": "string",
  "visibleBranches": [
    "string"
  ],
  "tags": [
    "string"
  ],
  "group": "string",
  "projectSite": "string",
  "contactPeople": [
    {
      "name": "string",
      "email": "string"
    }
  ],
  "editLinks": [
    {
      "branchName": "string",
      "link": "string"
    }
  ],
  "accessToken": "string",
  "isAccessLimited": "boolean"
}
Projects

Update information about project.

PUT /api/projects/{projectId}

Endpoint for updating information about project.

ProjectDto

Project information.

projectId

Project id.

type
string
in
path
Request Example
{
  "id": "string",
  "name": "string",
  "description": "string",
  "defaultBranch": "string",
  "visibleBranches": [
    "string"
  ],
  "tags": [
    "string"
  ],
  "group": "string",
  "projectSite": "string",
  "contactPeople": [
    {
      "name": "string",
      "email": "string"
    }
  ],
  "editLinks": [
    {
      "branchName": "string",
      "link": "string"
    }
  ],
  "accessToken": "string",
  "isAccessLimited": "boolean"
}
200 OK

Success

Projects

Delete specific project.

DELETE /api/projects/{projectId}

Endpoint for deleting specific project. Besides project information all branches and documentation files are deleting. Also documentation is deleted from search index (if search service is enabled).

projectId

Project id.

type
string
in
path
200 OK

Success

Projects

Get project access token.

GET /api/projects/{projectId}/accessToken

Endpoint for getting project token assigned to the project. That project token can be used to sending documentation files to all branches in project. Project token can be downloaded only by users assigned to specific project (if authorization service is enabled).

projectId

Project id.

type
string
in
path
200 OK
AccessTokenDto

Success

Response Example (200 OK) 
{
  "accessToken": "string"
}

Search

Search

Search by specific query (filter).

GET /api/search

Searching is done by connected search service (for example Azure search).

Query

(no description)

type
string
in
query
Page

(no description)

type
integer (int32)
in
query
Limit

(no description)

type
integer (int32)
in
query
200 OK
DocumentSearchResultDto[DocumentIndexDto]

Success

Response Example (200 OK) 
{
  "numberOfResults": "integer (int32)",
  "elapsedMilliseconds": "integer (int64)",
  "results": [
    {
      "document": {
        "id": "string",
        "url": "string",
        "fileUri": "string",
        "title": "string",
        "projectId": "string",
        "projectName": "string",
        "branchName": "string",
        "content": "string",
        "tags": [
          "string"
        ]
      },
      "highlights": "object",
      "score": "number (double)"
    }
  ]
}
Search

Search by specific query (filter) in specific project's branch.

GET /api/search/projects/{projectId}/branches/{branchName}

Searching is done by connected search service (for example Azure search). Serach is executed only in contect of specific project and branch.

Query

(no description)

type
string
in
query
Page

(no description)

type
integer (int32)
in
query
Limit

(no description)

type
integer (int32)
in
query
projectId

Project id.

type
string
in
path
branchName

Branch name.

type
string
in
path
200 OK
DocumentSearchResultDto[DocumentIndexDto]

Success

Response Example (200 OK) 
{
  "numberOfResults": "integer (int32)",
  "elapsedMilliseconds": "integer (int64)",
  "results": [
    {
      "document": {
        "id": "string",
        "url": "string",
        "fileUri": "string",
        "title": "string",
        "projectId": "string",
        "projectName": "string",
        "branchName": "string",
        "content": "string",
        "tags": [
          "string"
        ]
      },
      "highlights": "object",
      "score": "number (double)"
    }
  ]
}
Search

Add a new documentation information to search index.

POST /api/search/projects/{projectId}/branches/{branchName}

Endpoint is used to adding new documentation files to search index. It's batch operation so you can send multiple files at once.

List of documentations which should be added to search index.

DocumentIndexDto
projectId

Projetc id.

type
string
in
path
branchName

Branch name.

type
string
in
path
Request Example
[
  {
    "id": "string",
    "url": "string",
    "fileUri": "string",
    "title": "string",
    "projectId": "string",
    "projectName": "string",
    "branchName": "string",
    "content": "string",
    "tags": [
      "string"
    ]
  }
]
200 OK

Success

Search

Delete search index created for branch in specific project.

DELETE /api/search/projects/{projectId}/branches/{branchName}

Endpoint removes from search index information about branch and project. Searching shouldn't return any documents from that branch and project.

projectId

Project id.

type
string
in
path
branchName

Branch name.

type
string
in
path
200 OK

Success

Search

Refresh search index.

POST /api/search/projects/{projectId}/branches/{branchName}/refresh

Endpoint sending information to crawler service (it crawler service is enabled). Crawler is resposible for reindex all documentation in specific project and branch.

projectId

Project id.

type
string
in
path
branchName

Branch name.

type
string
in
path
200 OK

Success

Search

Get status about refreshing index.

GET /api/search/projects/{projectId}/branches/{branchName}/status

Endpoint returns information from crawler about refreshing status (if crawler service is enabled).

projectId

Project id.

type
string
in
path
branchName

Branch name.

type
string
in
path
200 OK
IndexStatusDto

Success

Response Example (200 OK) 
{
  "indexStatus": "integer (int32)",
  "projectId": "string",
  "branchName": "string",
  "startTime": "string (date-time)",
  "numberOfIndexedDocuments": "integer (int32)",
  "numberOfAllDocuments": "integer (int32)"
}

TableOfContents

TableOfContents

Get table of contents for specific branch in project.

GET /api/projects/{projectId}/branches/{branchName}/toc

Endpoint is resposible for returning table of contents contained in specific branch in project.

projectId

Project id.

type
string
in
path
branchName

Branch name.

type
string
in
path
200 OK

Success

Tags

Tags

Get all tags.

GET /api/tags

Endpoint returns all tags which are defined in all documentation projects.

200 OK

Success

Response Example (200 OK) 
[
  "string"
]

Users

Users

Get list of users.

GET /api/users

Endpoint returns all users defined in ths authorization service.

200 OK
UserDto

Success

Response Example (200 OK) 
[
  {
    "id": "string",
    "name": "string",
    "role": "integer (int32)",
    "accessToken": "string",
    "projects": [
      "string"
    ]
  }
]
Users

Create a new user.

POST /api/users

Endpoint for creating new user information.

UserDto

User information.

Request Example
{
  "id": "string",
  "name": "string",
  "role": "integer (int32)",
  "accessToken": "string",
  "projects": [
    "string"
  ]
}
200 OK

Success

Users

Get specific user.

GET /api/users/{id}

Endpoint returns information about specific user.

id

User id.

type
string
in
path
200 OK

Success

Users

Update user information.

PUT /api/users/{id}

Endpoint for updating user information.

UserDto

User information.

id

User id.

type
string
in
path
Request Example
{
  "id": "string",
  "name": "string",
  "role": "integer (int32)",
  "accessToken": "string",
  "projects": [
    "string"
  ]
}
200 OK

Success

Users

Delete user.

DELETE /api/users/{id}

Endpoint for deleting user.

id

User id.

type
string
in
path
200 OK

Success

Users

Refresh access token.

PUT /api/users/{id}/refreshToken

Endpoint is resposible for saving new access token for user.

AccessTokenDto

New access token.

id

User id.

type
string
in
path
Request Example
{
  "accessToken": "string"
}
200 OK

Success

Schema Definitions

ExtendedBranchDto: object

siteName: string
docsDir: string
name: string
mkDocsYaml: string
Example
{
  "siteName": "string",
  "docsDir": "string",
  "name": "string",
  "mkDocsYaml": "string"
}

BranchDto: object

name: string
mkDocsYaml: string
Example
{
  "name": "string",
  "mkDocsYaml": "string"
}

BaseDocumentDto: object

uri: string
name: string
conentType: string
Example
{
  "uri": "string",
  "name": "string",
  "conentType": "string"
}

DocumentDto: object

content: string (byte)
uri: string
name: string
conentType: string
Example
{
  "content": "string (byte)",
  "uri": "string",
  "name": "string",
  "conentType": "string"
}

FileContentResult: object

fileContents: string (byte)
contentType: string
fileDownloadName: string
Example
{
  "fileContents": "string (byte)",
  "contentType": "string",
  "fileDownloadName": "string"
}

FilteredResutsDto[ProjectDto]: object

results: object[]
allResults: integer (int32)
Example
{
  "results": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "defaultBranch": "string",
      "visibleBranches": [
        "string"
      ],
      "tags": [
        "string"
      ],
      "group": "string",
      "projectSite": "string",
      "contactPeople": [
        {
          "name": "string",
          "email": "string"
        }
      ],
      "editLinks": [
        {
          "branchName": "string",
          "link": "string"
        }
      ],
      "accessToken": "string",
      "isAccessLimited": "boolean"
    }
  ],
  "allResults": "integer (int32)"
}

ProjectDto: object

id: string
name: string
description: string
defaultBranch: string
visibleBranches: string[]
tags: string[]
group: string
projectSite: string
contactPeople: object[]
editLinks: object[]
accessToken: string
isAccessLimited: boolean
Example
{
  "id": "string",
  "name": "string",
  "description": "string",
  "defaultBranch": "string",
  "visibleBranches": [
    "string"
  ],
  "tags": [
    "string"
  ],
  "group": "string",
  "projectSite": "string",
  "contactPeople": [
    {
      "name": "string",
      "email": "string"
    }
  ],
  "editLinks": [
    {
      "branchName": "string",
      "link": "string"
    }
  ],
  "accessToken": "string",
  "isAccessLimited": "boolean"
}

ContactPersonDto: object

name: string
email: string
Example
{
  "name": "string",
  "email": "string"
}

EditLinkDto: object

branchName: string
link: string
Example
{
  "branchName": "string",
  "link": "string"
}

AccessTokenDto: object

accessToken: string
Example
{
  "accessToken": "string"
}

DocumentSearchResultDto[DocumentIndexDto]: object

numberOfResults: integer (int32)
elapsedMilliseconds: integer (int64)
results: object[]
Example
{
  "numberOfResults": "integer (int32)",
  "elapsedMilliseconds": "integer (int64)",
  "results": [
    {
      "document": {
        "id": "string",
        "url": "string",
        "fileUri": "string",
        "title": "string",
        "projectId": "string",
        "projectName": "string",
        "branchName": "string",
        "content": "string",
        "tags": [
          "string"
        ]
      },
      "highlights": "object",
      "score": "number (double)"
    }
  ]
}

SearchResultDto[DocumentIndexDto]: object

document: DocumentIndexDto
highlights: object
score: number (double)
Example
{
  "document": {
    "id": "string",
    "url": "string",
    "fileUri": "string",
    "title": "string",
    "projectId": "string",
    "projectName": "string",
    "branchName": "string",
    "content": "string",
    "tags": [
      "string"
    ]
  },
  "highlights": "object",
  "score": "number (double)"
}

DocumentIndexDto: object

id: string
url: string
fileUri: string
title: string
projectId: string
projectName: string
branchName: string
content: string
tags: string[]
Example
{
  "id": "string",
  "url": "string",
  "fileUri": "string",
  "title": "string",
  "projectId": "string",
  "projectName": "string",
  "branchName": "string",
  "content": "string",
  "tags": [
    "string"
  ]
}

IndexStatusDto: object

indexStatus: integer (int32) , x ∈ { 0 , 1 }
projectId: string
branchName: string
startTime: string (date-time)
numberOfIndexedDocuments: integer (int32)
numberOfAllDocuments: integer (int32)
Example
{
  "indexStatus": "integer (int32)",
  "projectId": "string",
  "branchName": "string",
  "startTime": "string (date-time)",
  "numberOfIndexedDocuments": "integer (int32)",
  "numberOfAllDocuments": "integer (int32)"
}

UserDto: object

id: string
name: string
role: integer (int32) , x ∈ { 0 , 1 , 2 , 3 }
accessToken: string
projects: string[]
Example
{
  "id": "string",
  "name": "string",
  "role": "integer (int32)",
  "accessToken": "string",
  "projects": [
    "string"
  ]
}
Documentation by Spectacle