1 | # @kweli/cs-rest
|
2 |
|
3 | Simple authentication and REST calls for OpenText Content Server.
|
4 |
|
5 | ## Features
|
6 |
|
7 | - Provides a simplified interface for managing authentication with the OpenText Content Server REST API
|
8 | - Automatically adds the `OTCSTicket` header to each subsequent request
|
9 | - Refreshes the `OTCSTicket` token automatically (minimising token expiration errors)
|
10 | - Simplifies POST, PUT, & PATCH requests (since Content Server doesn't support the `application/json` content type)
|
11 | - Based on the [axios](https://github.com/axios/axios) HTTP client
|
12 | - Works with Node.js and the browser
|
13 |
|
14 | ## Installing
|
15 |
|
16 | Using npm:
|
17 |
|
18 | ```bash
|
19 | $ npm install @kweli/cs-rest
|
20 | ```
|
21 |
|
22 | Using yarn:
|
23 |
|
24 | ```bash
|
25 | $ yarn add @kweli/cs-rest
|
26 | ```
|
27 |
|
28 | Using unpkg CDN:
|
29 |
|
30 | ```html
|
31 | <script src="https://cdn.jsdelivr.net/npm/es6-promise@4/dist/es6-promise.auto.min.js"></script>
|
32 | <script src="https://unpkg.com/axios/dist/axios.min.js"></script>
|
33 | <script src="https://unpkg.com/@kweli/cs-rest"></script>
|
34 | ```
|
35 |
|
36 | ## Example
|
37 |
|
38 | Authenticate with a username and password and get the details of a node:
|
39 |
|
40 | ```js
|
41 | const CSREST = require('@kweli/cs-rest')
|
42 |
|
43 | // session wraps an axios instance
|
44 | const session = new CSREST.Session({
|
45 | baseURL: 'https://.../cs.exe',
|
46 | username: 'Admin',
|
47 | password: '******'
|
48 | })
|
49 |
|
50 | // a Session instance can issue authenticated requests to Content Server
|
51 | const response = await session.get('/api/v1/nodes/2000')
|
52 | ```
|
53 |
|
54 | Authenticate with an `OTCSTicket`:
|
55 |
|
56 | ```js
|
57 | const session = new CSREST.Session({
|
58 | baseURL: 'https://.../cs.exe',
|
59 | otcsticket: '<token>'
|
60 | })
|
61 | ```
|
62 |
|
63 | ## cs-rest API
|
64 |
|
65 | 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).
|
66 |
|
67 | Content Server returns a fresh `OTCSTicket` with each successful API call. The `Session` instance automatically retains it for the subsequent request.
|
68 |
|
69 | #### POST, PUT, & PATCH
|
70 |
|
71 | 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:
|
72 |
|
73 | ```js
|
74 | const formData = new FormData()
|
75 | formData.append('type', 0)
|
76 | formData.append('parent_id', 2000)
|
77 | formDAta.append('name', 'My New Folder')
|
78 |
|
79 | const response = await session.post('api/v2/nodes', formData)
|
80 | ```
|
81 |
|
82 | The `Session` class provides a `postForm` (also `putForm` and `patchForm`) method to simplify this:
|
83 |
|
84 | ```js
|
85 | const response = await session.postForm('api/v2/nodes', {
|
86 | type: 0,
|
87 | parent_id: 2000,
|
88 | name: 'My New Folder'
|
89 | })
|
90 | ```
|
91 |
|
92 | #### axios instance
|
93 |
|
94 | The underlying `axios` instance is available if these methods don't suffice:
|
95 |
|
96 | ```js
|
97 | const axios = session.axios
|
98 | ```
|
99 |
|
100 | #### Thin Wrapper
|
101 |
|
102 | 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.
|
103 |
|
104 | For example, there is a method for creating a new folder:
|
105 |
|
106 | ```js
|
107 | const response = await session.nodes.addFolder(2000, 'My New Folder')
|
108 | ```
|
109 |
|
110 | A method also exists for uploading a document, where `file` is either:
|
111 |
|
112 | - a browser [File](https://developer.mozilla.org/en-US/docs/Web/API/File) object (e.g,. from drag and drop); or
|
113 | - a local file path, when using Node.js (e.g., `c:/temp/file.pdf`.
|
114 |
|
115 | ```js
|
116 | const response = await session.nodes.addDocument(2000, file)
|
117 | ```
|
118 |
|
119 | See the `src/` directory for more examples.
|
120 |
|
121 | ## Credits
|
122 |
|
123 | - [OpenText Content Server REST API](https://developer.opentext.com/webaccess/#url=%2Fawd%2Fresources%2Fapis%2Fcs-rest-api-for-cs-16-s&tab=501)
|
124 | - [Kwe.li GmbH](https://kwe.li/)
|
125 |
|
126 | ## License
|
127 |
|
128 | [MIT](LICENSE) |
\ | No newline at end of file |