Gitbook Client for Java

This Java client connects with GitBook.com, enabling simple interaction with their API. It also includes a Spring Boot starter for quick integration.

• Gitbook Client for Java
• Installation
• Client
  • Configuration
  • Usage
    • API
      • Get API Informations
    • User
      • Find the Currently Authenticated User
      • Find a User by ID
    • Organization
      • Stream Organizations
      • Find an Organization by ID
    • Site
      • Stream Sites
      • Find a Site by ID
      • Get a Site Structure
    • Space
      • Stream Spaces
      • Find a Space by ID
      • Get a Space Content page by path
      • List all Space Pages
      • Stream Space Files
    • Change Requests
      • Stream Change Requests
      • Find a Change Requests by ID
      • Find a Change Requests by Space Number
      • Get a Change Request Content page by path
      • List all Change Request Pages
      • Stream Change Request Files
  • Document Node Objects
• Spring Boot Starter
  • Client

Installation

<properties>
<gitbook.version>0.2.0</gitbook.version>
</properties>
<dependencies>
<dependency>
<groupId>dev.caceresenzo.gitbook</groupId>
<artifactId>gitbook-client</artifactId>
<version>${gitbook.version}</version>
</dependency>
</dependencies>

Client

Configuration

GitBookClientclient = GitBookClient.builder()
.accessToken("gb_api_a0b1c2d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t9")
.build();
/* stay unauthenticated */GitBookClientclient = GitBookClient.builder()
.unauthenticated()
.build();

Usage

API

Get API Informations

ApiInfoinfo = client.getApiInfo();

User

Find the Currently Authenticated User

The user will not be found if the access token is missing or invalid.

Optional<User> user = client.findCurrentUser();

Find a User by ID

StringuserId = "a0b1c2d3e4f5g6h7i8j9k0l1m2n3";
Optional<User> user = client.findUserById(userId);

Organization

Stream Organizations

Stream<Organization> organizations = client.findAllOrganizations();
/* or get a list via */List<Organization> organizations = client.findAllOrganizations().toList();

Find an Organization by ID

StringorganizationId = "a0b1c2d3e4f5g6h7i8j9k0l1m2n3";
Optional<Organization> organization = client.findOrganization(organizationId);

Site

Stream Sites

StringorganizationId = "a0b1c2d3e4f5g6h7i8j9k0l1m2n3";
Stream<Site> sites = client.findAllSites(organizationId);
/* or get a list via */List<Site> sites = client.findAllSites(organizationId).toList();

Find a Site by ID

StringorganizationId = "a0b1c2d3e4f5g6h7i8j9k0l1m2n3";
StringsiteId = "a0b1c2d3e4f5g6h7i8j9k0l1m2n3";
Optional<Site> site = client.findSiteById(organizationId, siteId);

Get a Site Structure

StringorganizationId = "a0b1c2d3e4f5g6h7i8j9k0l1m2n3";
StringsiteId = "a0b1c2d3e4f5g6h7i8j9k0l1m2n3";
Optional<SiteStructure> siteStructure = client.getSiteStructure(organizationId, siteId);

Space

Stream Spaces

StringorganizationId = "a0b1c2d3e4f5g6h7i8j9k0l1m2n3";
Stream<Space> spaces = client.findAllSpaces(organizationId);
/* or get a list via */List<Space> spaces = client.findAllSpaces(organizationId).toList();

Find a Space by ID

StringspaceId = "a0b1c2d3e4f5g6h7i8j9k0l1m2n3";
Optional<Space> space = client.findSpace(spaceId);

Get a Space Content page by path

StringspaceId = "a0b1c2d3e4f5g6h7i8j9k0l1m2n3";
StringpagePath = "/hello";
Optional<RevisionPage> content = client.getSpaceContent(spaceId, pagePath);

List all Space Pages

StringspaceId = "a0b1c2d3e4f5g6h7i8j9k0l1m2n3";
Optional<List<Page>> content = client.getSpacePages(spaceId);

Stream Space Files

StringspaceId = "a0b1c2d3e4f5g6h7i8j9k0l1m2n3";
Stream<File> files = client.findAllSpaceFiles(spaceId);
/* or get a list via */List<File> files = client.findAllSpaceFiles(spaceId).toList();

Change Requests

Stream Change Requests

StringspaceId = "a0b1c2d3e4f5g6h7i8j9k0l1m2n3";
Stream<ChangeRequest> changeRequests = client.findAllChangeRequests(spaceId);
/* or get a list via */List<ChangeRequest> changeRequests = client.findAllChangeRequests(spaceId).toList();
/* or only filter by status */Stream<ChangeRequest> archivedChangeRequests = client.findAllChangeRequests(spaceId, ChangeRequest.Status.ARCHIVED);
List<ChangeRequest> archivedChangeRequests = client.findAllChangeRequests(spaceId, ChangeRequest.Status.ARCHIVED).toList();

Find a Change Requests by ID

StringspaceId = "a0b1c2d3e4f5g6h7i8j9k0l1m2n3";
StringchangeRequestId = "a0b1c2d3e4f5g6h7i8j9k0l1m2n3";
Optional<ChangeRequest> changeRequest = client.findChangeRequestById(spaceId, changeRequestId);

Find a Change Requests by Space Number

StringspaceId = "a0b1c2d3e4f5g6h7i8j9k0l1m2n3";
StringchangeRequestNumber = 42;
Optional<ChangeRequest> changeRequest = client.findChangeRequestByNumber(spaceId, changeRequestNumber);

Get a Change Request Content page by path

StringspaceId = "a0b1c2d3e4f5g6h7i8j9k0l1m2n3";
StringchangeRequestId = "a0b1c2d3e4f5g6h7i8j9k0l1m2n3";
StringpagePath = "/hello";
Optional<RevisionPage> content = client.getChangeRequestContent(spaceId, changeRequestId, pagePath);

List all Change Request Pages

StringspaceId = "a0b1c2d3e4f5g6h7i8j9k0l1m2n3";
StringchangeRequestId = "a0b1c2d3e4f5g6h7i8j9k0l1m2n3";
Optional<List<Page>> pages = client.getChangeRequestPages(spaceId, changeRequestId);

Stream Change Request Files

StringspaceId = "a0b1c2d3e4f5g6h7i8j9k0l1m2n3";
StringchangeRequestId = "a0b1c2d3e4f5g6h7i8j9k0l1m2n3";
Stream<File> files = client.findAllChangeRequestFiles(spaceId, changeRequestId);
/* or get a list via */List<File> files = client.findAllChangeRequestFiles(spaceId, changeRequestId).toList();

Document Node Objects

All document objects have a corresponding Java class, making it easy to query information about the content. Most of these classes have children that can be used to traverse the tree.

Testing the block types

switch (block) {
caseBlock.Codecode -> {};
caseBlock.CodeLinecodeLine -> { }
caseBlock.Columnscolumns -> { }
caseBlock.Columncolumn -> { }
caseBlock.Dividerdivider -> { }
caseBlock.Drawingdrawing -> { }
caseBlock.Embedembed -> { }
caseBlock.Expandableexpandable -> { }
caseBlock.Heading1heading1 -> { }
caseBlock.Heading2heading2 -> { }
caseBlock.Heading3heading3 -> { }
caseBlock.Hinthint -> { }
caseBlock.Imagesimages -> { }
caseBlock.Imageimage -> { }
caseBlock.ListItemlistItem -> { }
caseBlock.OrderedListorderedList -> { }
caseBlock.UnorderedListunorderedList -> { }
caseBlock.TaskListtaskList -> { }
caseBlock.Mathmath -> { }
caseBlock.PageLinkpageLink -> { }
caseBlock.Paragraphparagraph -> { }
caseBlock.Quotequote -> { }
caseBlock.Stepperstepper -> { }
caseBlock.StepperStepstepperStep -> { }
caseBlock.Tabletable -> { }
caseBlock.Tabstabs -> { }
caseBlock.TabsItemtabsItem -> { }
caseBlock.Updatesupdates -> { }
caseBlock.Updateupdate -> { }
/* Fallback */caseBlock.Otherother -> { }
}

Testing the inline types

switch (inline) {
caseInline.Annotationannotation -> { }
caseInline.Linklink -> { }
caseInline.Mentionmention -> { }
caseInline.Mathmath -> { }
caseInline.Buttonbutton -> { }
caseInline.Emojiemoji -> { }
caseInline.Iconicon -> { }
caseInline.Imageimage -> { }
/* Fallback */caseInline.Otherother -> { }
}

Testing the mark types

switch (mark) {
caseMark.Bold__ -> { }
caseMark.Italic__ -> { }
caseMark.Strikethrough__ -> { }
caseMark.Superscript__ -> { }
caseMark.Subscript__ -> { }
caseMark.Code__ -> { }
caseMark.Keyboard__ -> { }
caseMark.Colorcolor -> { }
/* Fallback */caseMark.Other__ -> { }
}

Spring Boot Starter

There is a Spring Boot auto-configuration available.

<dependencies>
<dependency>
<groupId>dev.caceresenzo.gitbook</groupId>
<artifactId>gitbook-spring-boot-starter</artifactId>
<version>${gitbook.version}</version>
</dependency>
</dependencies>

Client

This is always enabled. An access token can be specified in the configuration:

gitbook:
access-token: gb_api_a0b1c2d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t9