@kweli/cs-rest/README.md

Simple authentication and REST calls for OpenText Content Server.

# @kweli/cs-rest

Simple authentication and REST calls for OpenText Content Server.

## Features

- Provides a simplified interface for managing authentication with the OpenText Content Server REST API
- Refreshes the `OTCSTicket` token automatically (minimising token expiration errors)
- Simplifies POST, PUT, & PATCH requests (since Content Server doesn't support the `application/json` content type)
- Based on the [axios](https://github.com/axios/axios) HTTP client
- Works with Node.js and the browser

## Breaking Changes v2

- The `baseURL` parameter was renamed `baseUrl`.

## Installing

Using npm:

```bash
npm install @kweli/cs-rest
```

Using yarn:

```bash
yarn add @kweli/cs-rest
```

## Example

Authenticate with a username and password and get the details of a node:

```js
import { Session } from "@kweli/cs-rest";

// session wraps an axios instance
const session = new Session({
  baseUrl: "https://.../cs.exe",
  username: "Admin",
  password: "******",
});

// a Session instance can issue authenticated requests to Content Server
const response = await session.get("/api/v1/nodes/2000");
```

Authenticate with an `OTCSTicket`:

```js
const session = new Session({
  baseUrl: "https://.../cs.exe",
  otcsticket: "<token>",
});
```

## cs-rest API

Requests can be made with the `get`, `post`, `put`, `patch`, `delete`, and `options` methods on the `Session` instance. These have the same interface as the respective methods in [axios](https://github.com/axios/axios).

Content Server returns a fresh `OTCSTicket` with each successful API call. The `Session` instance automatically retains it for the subsequent request.

#### POST, PUT, & PATCH

The OpenText Content Server REST API doesn't accept requests that use the `application/json` content type. This means POST, PUT, & PATCH requests need to use a content type of `multipart/form-data`, which makes writing a request a little more verbose. For example, to create a new folder:

```js
const formData = new FormData();
formData.append("type", 0);
formData.append("parent_id", 2000);
formDAta.append("name", "My New Folder");

const response = await session.post("api/v2/nodes", formData);
```

The `Session` class provides a `postForm` (also `putForm` and `patchForm`) method to simplify this:

```js
const response = await session.postForm("api/v2/nodes", {
  type: 0,
  parent_id: 2000,
  name: "My New Folder",
});
```

#### axios instance

The underlying `axios` instance is available if these methods don't suffice:

```js
const axios = session.axios;
```

#### Wrapper

The `Session` class provides a few convenience methods for performing commonly used REST requests. By no means is this complete, and it's possible the API will change in the future.

For example, there is a method for creating a new folder:

```js
const response = await session.nodes.addFolder(2000, "My New Folder");
```

A method also exists for uploading a document, where `file` is either:

- a browser [File](https://developer.mozilla.org/en-US/docs/Web/API/File) object (e.g,. from drag and drop); or
- a local file path, when using Node.js (e.g., `c:/temp/file.pdf`.

```js
const response = await session.nodes.addDocument(2000, file);
```

## Credits

- [OpenText Content Server REST API](https://developer.opentext.com/ce/products/extended-ecm/apis/content-server-233-rest-api)
- [Kwe.li GmbH](https://kwe.li/)

## License

[MIT](LICENSE)