# Introduction

This documentation is intended to get you up-and-running with the GitBook APIs. We’ll cover everything you need to know, from authentication, to manipulating results, to combining results with other services.

The REST APIs provide programmatic access to read and write GitBook data. List books, edit content, proofread text, and more. The REST API identifies users using basic auth; responses are available in JSON.

[![Build Status](https://travis-ci.org/firebase/firebase-admin-node.svg?branch=master)](https://travis-ci.org/firebase/firebase-admin-node)

## Firebase Admin Node.js SDK

### Table of Contents

* Overview
* Installation
* Contributing
* Documentation
* Acknowledgments
* License

### Overview

[Firebase](https://firebase.google.com) provides the tools and infrastructure you need to develop your app, grow your user base, and earn money. The Firebase Admin Node.js SDK enables access to Firebase services from privileged environments (such as servers or cloud) in Node.js.

For more information, visit the [Firebase Admin SDK setup guide](https://firebase.google.com/docs/admin/setup/).

### Installation

The Firebase Admin Node.js SDK is available on npm as `firebase-admin`:

```bash
$ npm install --save firebase-admin
```

To use the module in your application, `require` it from any JavaScript file:

```javascript
var admin = require("firebase-admin");
```

If you are using ES2015, you can `import` the module instead:

```javascript
import * as admin from "firebase-admin";
```

### Contributing

Please refer to the [CONTRIBUTING page](https://app.gitbook.com/s/-L3E3qi2Mgs4CS5b6NY-/CONTRIBUTING.md) for more information about how you can contribute to this project. We welcome bug reports, feature requests, code review feedback, and also pull requests.

### Documentation

* [Setup Guide](https://firebase.google.com/docs/admin/setup/)
* [Database Guide](https://firebase.google.com/docs/database/admin/start/)
* [Authentication Guide](https://firebase.google.com/docs/auth/admin/)
* [Cloud Messaging Guide](https://firebase.google.com/docs/cloud-messaging/admin/)
* [API Reference](https://firebase.google.com/docs/reference/admin/node/)
* [Release Notes](https://firebase.google.com/support/release-notes/admin/node/)

### Acknowledgments

Thanks to the team at [Casetext](https://casetext.com/) for transferring ownership of the `firebase-admin` npm module over to the Firebase team and for their longtime use and support of the Firebase platform.

### License

Firebase Admin Node.js SDK is licensed under the [Apache License, version 2.0](http://www.apache.org/licenses/LICENSE-2.0).

Your use of Firebase is governed by the [Terms of Service for Firebase Services](https://firebase.google.com/terms/).

Hello world

{% hint style="danger" %}
Deprecated API, checkout the **new GitBook**!
{% endhint %}

## Schema

All API access is over HTTPS, and accessed through `https://api.gitbook.com`. All data is sent and received as **JSON**.

Hello world

{% tabs %}
{% tab title="HTTP" %}

```
$ curl -i https://api.gitbook.com/author/gitbookio

HTTP/1.1 200 OK
Server: GitBook.com
Connection: keep-alive
Content-Type: application/json; charset=utf-8
Content-Length: 275
Etag: W/"113-25d22777"
Date: Thu, 11 Jun 2015 14:49:26 GMT
Via: 1.1 vegur

{ ... }
```

{% endtab %}

{% tab title="JavaScript" %}
Install the GitBook API client from NPM:

```bash
$ npm install gitbook-api
```

Initialize a client:

```javascript
const GitBook = require('gitbook-api');

const client = new GitBook();
```

{% endtab %}

{% tab title="Go" %}
Install the GitBook API client using `go get`:

```bash
$ go get github.com/GitbookIO/go-gitbook-api
```

Initialize a client:

```go
package main

import (
    "fmt"
    "github.com/GitbookIO/go-gitbook-api"
)

func main() {
    api := gitbook.NewAPI(gitbook.APIOptions{})
}
```

{% endtab %}
{% endtabs %}

## Authentication

While the API provides multiple methods for authentication, we strongly recommend using [OAuth](https://adaptive-docs.gitbook-staging.com/overview/oauth) for production applications. The other methods provided are intended to be used for scripts or testing (i.e., cases where full OAuth would be overkill).

Third party applications that rely on GitBook for authentication should not ask for or collect GitBook credentials. Instead, they should use the OAuth web flow.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

The API supports Basic Authentication as defined in [RFC2617](http://www.ietf.org/rfc/rfc2617.txt) with a few slight differences.

Requests that require authentication will return `404 Not Found`, instead of `403 Forbidden`, in some places. This is to prevent the accidental leakage of private books to unauthorized users.

{% tabs %}
{% tab title="HTTP" %}

#### Via Username and Password

To use Basic Authentication with the GitBook API, simply send the username and password associated with the account.

For example, if you’re accessing the API via cURL, the following command would authenticate you if you replace with your GitBook username. (cURL will prompt you to enter the password.)

Alternatively, you can use personal access tokens or OAuth tokens instead of your password.

```bash
$ curl -u <username>:<password or token> https://api.gitbook.com/account
```

#### Via OAuth Tokens

The access token allows you to make requests to the API on a behalf of a user.

```bash
$ curl -H "Authorization: token OAUTH-TOKEN" https://api.gitbook.com/account
```

{% endtab %}

{% tab title="JavaScript" %}

#### Via Username and Password

```javascript
const client = new GitBook({
    username: 'MyUsername',
    token: 'password'
});
```

#### Via OAuth Tokens

```javascript
const client = new GitBook({
    token: 'oauth token'
});
```

{% endtab %}

{% tab title="Go" %}

#### Via Username and Password

```go
api := gitbook.NewAPI(gitbook.APIOptions{
    Username: "username",
    Password: "password",
})
```

#### Via OAuth Tokens

```go
api := gitbook.NewAPI(gitbook.APIOptions{
    Token: "token"
})
```

{% endtab %}
{% endtabs %}

## Errors

GitBook uses conventional HTTP response codes to indicate the success or failure of an API request.

In general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the `5xx` range indicate an error with Stripe's servers (these are rare).

Not all errors map cleanly onto HTTP response codes, however.

{% tabs %}
{% tab title="HTTP" %}

#### HTTP status code summary

| Status              | Description                                                              |
| ------------------- | ------------------------------------------------------------------------ |
| `200 - OK`          | Everything worked as expected.                                           |
| `400 - Bad Request` | The request was unacceptable, often due to missing a required parameter. |
| `404 - Not Found`   | The requested resource doesn't exist.                                    |

#### Example Response

```javascript
{
    "error": "A human-readable message providing more details about the error.",
    "code": 400
}
```

{% endtab %}

{% tab title="JavaScript" %}
All API calls return promises.

```javascript
client.books()
.then(function(result) {

}, function(err) {

});
```

The status code can be access using the `code` property of the error: `err.code`.
{% endtab %}

{% tab title="Go" %}
All API calls return both the result and the error:

```go
book, err := api.Book.Get("gitbookio/javascript")
```

{% endtab %}
{% endtabs %}

### Pagination <a href="#pagination" id="pagination"></a>

Requests that return multiple items will be paginated to 50 items by default.

You can specify further pages with the `?page` parameter. For some resources, you can also set a custom page size up to 100 with the `?limit`.

{% tabs %}
{% tab title="HTTP" %}
Paginated results will be returned with information about the page context.

```javascript
{
    list: [ ... ],
    page: 0,
    limit: 50,
    total: 0
}
```

{% endtab %}

{% tab title="JavaScript" %}
Paginated methods return a `Page` object.

Calling `page.next()` or `page.prev()` will fetch the next/previous page and return a promise with a new `Page` object.

`page.list: Array<Mixed>` contains the items of current page.

`page.total: Number` is count of all elements.

```javascript
client.books()
.then(function(page) {
    console.log('Total:', page.total);
    console.log('In this page:', page.list.length);

    // Fetch next page
    return page.next();
}, function(err) {
    // Error occured
});
```

{% endtab %}
{% endtabs %}

### Enterprise

All API endpoints are prefixed with the following URL: `http(s)://hostname/api/`.

Most methods require an authentication when using an enterprise instance.

{% tabs %}
{% tab title="HTTP" %}

```bash
$ curl https://gitbook/myenterprise.com/api/books/all
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const client = new GitBook({
    host: 'http://gitbook.mycompany.com'
});
```

{% endtab %}

{% tab title="Go" %}

```go
api := gitbook.NewAPI(gitbook.APIOptions{
    Host: "http://gitbook.mycompany.com/api/"
})
```

{% endtab %}
{% endtabs %}

### Help and Support

We're always happy to help out with your applications or any other questions you might have. You can ask a question or signal an issue using inline comments.