Public API docs
This commit is contained in:
parent
00c2145116
commit
e82654ab7f
|
@ -24,7 +24,6 @@ import Collection from 'scenes/Collection';
|
|||
import Document from 'scenes/Document';
|
||||
import Search from 'scenes/Search';
|
||||
import SlackAuth from 'scenes/SlackAuth';
|
||||
import Flatpage from 'scenes/Flatpage';
|
||||
import ErrorAuth from 'scenes/ErrorAuth';
|
||||
import Error404 from 'scenes/Error404';
|
||||
|
||||
|
@ -33,8 +32,6 @@ import ScrollToTop from 'components/ScrollToTop';
|
|||
import Layout from 'components/Layout';
|
||||
import RouteSidebarHidden from 'components/RouteSidebarHidden';
|
||||
|
||||
import flatpages from 'static/flatpages';
|
||||
|
||||
import { matchDocumentSlug } from 'utils/routeHelpers';
|
||||
|
||||
let DevTools;
|
||||
|
@ -92,7 +89,6 @@ const Auth = ({ children }: AuthProps) => {
|
|||
};
|
||||
|
||||
const notFoundSearch = () => <Search notFound />;
|
||||
const Api = () => <Flatpage title="API" content={flatpages.api} />;
|
||||
const DocumentNew = () => <Document newDocument />;
|
||||
const RedirectDocument = ({ match }: { match: Object }) => (
|
||||
<Redirect to={`/doc/${match.params.documentSlug}`} />
|
||||
|
@ -141,7 +137,6 @@ render(
|
|||
|
||||
<Route exact path="/search" component={Search} />
|
||||
<Route exact path="/search/:query" component={Search} />
|
||||
<Route exact path="/developers" component={Api} />
|
||||
|
||||
<Route path="/404" component={Error404} />
|
||||
|
||||
|
|
|
@ -23,6 +23,10 @@ class AccountMenu extends Component {
|
|||
this.props.ui.setActiveModal('settings');
|
||||
};
|
||||
|
||||
handleApi = () => {
|
||||
window.location.href = '/developers';
|
||||
};
|
||||
|
||||
handleLogout = () => {
|
||||
this.props.auth.logout();
|
||||
window.location.href = BASE_URL;
|
||||
|
@ -30,19 +34,12 @@ class AccountMenu extends Component {
|
|||
|
||||
render() {
|
||||
return (
|
||||
<DropdownMenu
|
||||
style={{ marginRight: 10, marginTop: -10 }}
|
||||
label={this.props.label}
|
||||
>
|
||||
<DropdownMenuItem onClick={this.handleOpenSettings}>
|
||||
Settings
|
||||
</DropdownMenuItem>
|
||||
<DropdownMenu style={{ marginRight: 10, marginTop: -10 }} label={this.props.label}>
|
||||
<DropdownMenuItem onClick={this.handleOpenSettings}>Settings</DropdownMenuItem>
|
||||
<DropdownMenuItem onClick={this.handleOpenKeyboardShortcuts}>
|
||||
Keyboard shortcuts
|
||||
</DropdownMenuItem>
|
||||
<Link to="/developers">
|
||||
<DropdownMenuItem>API documentation</DropdownMenuItem>
|
||||
</Link>
|
||||
<DropdownMenuItem onClick={this.handleApi}>API documentation</DropdownMenuItem>
|
||||
<DropdownMenuItem onClick={this.handleLogout}>Logout</DropdownMenuItem>
|
||||
</DropdownMenu>
|
||||
);
|
||||
|
|
|
@ -1,199 +0,0 @@
|
|||
# Outline API
|
||||
|
||||
_Our API is currently in beta and we might make minor adjustments._
|
||||
|
||||
## Making requests
|
||||
|
||||
Outline's API follows JSON RPC style conventions where each API endpoint is a method on `https://www.getoutline.com/api/<METHOD>`. Each request needs to be made using HTTPS and both `GET` and `POST` (recommended) methods are supported.
|
||||
|
||||
For `GET` requests query string parameters are expected (e.g. `/api/document.info?id=...&token=...`). When making `POST` requests, request parameters are parsed depending on `Content-Type` header. To make a call using JSON payload, one must pass `Content-Type: application/json` header:
|
||||
|
||||
```shell
|
||||
curl 'https://www.getoutline.com/api/documents.info?id=outline-api-NTpezNwhUP'\
|
||||
-H 'authorization: Bearer <API KEY>'\
|
||||
-H 'content-type: application/json'\
|
||||
-H 'accept: application/json'
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
To access private API endpoints, you must provide a valid API key. You can create new API keys in your [account settings](https://www.getoutline.com/settings). Be careful when handling your keys as they give access to all of your documents.
|
||||
|
||||
To authenticate with Outline API, you can supply the API key as a header (`Authorization: Bearer <API KEY>`) or as part of the payload using `token` parameter.
|
||||
|
||||
Some API endpoints allow unauhenticated requests for public resources and they can be called without an API key.
|
||||
|
||||
## Errors
|
||||
|
||||
All successful API requests will be returned with `200` status code and `ok: true` in the response payload. If there's an error while making the request, appropriate status code is returned with the `error` message:
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": false,
|
||||
"error: "Not Found"
|
||||
}
|
||||
```
|
||||
|
||||
## Methods
|
||||
|
||||
### `user.info` - Get current user
|
||||
|
||||
This method returns the information for currently logged in user.
|
||||
|
||||
#### Arguments
|
||||
|
||||
`https://www.getoutline.com/api/user.info`
|
||||
|
||||
Parameter | Description
|
||||
------------ | -------------
|
||||
`token` | Authentication token
|
||||
|
||||
---
|
||||
|
||||
### `user.s3Upload` - Gets S3 upload credentials
|
||||
|
||||
You can upload small files and images as part of your documents. All files are stored using Amazon S3. Instead of uploading files to Outline, you need to upload them directly to S3 with special credentials which can be obtained through this endpoint.
|
||||
|
||||
#### Arguments
|
||||
|
||||
`https://www.getoutline.com/api/user.s3Upload`
|
||||
|
||||
Parameter | Description
|
||||
------------ | -------------
|
||||
`token` | Authentication token
|
||||
`filename` | Filename of the uploaded file
|
||||
`kind` | Mimetype of the document
|
||||
`size` | Filesize of the document
|
||||
|
||||
---
|
||||
|
||||
### `collections.list` - List your document collections
|
||||
|
||||
List all your document collections.
|
||||
|
||||
#### Arguments
|
||||
|
||||
`https://www.getoutline.com/api/collections.list`
|
||||
|
||||
Parameter | Description
|
||||
------------ | -------------
|
||||
`token` | Authentication token
|
||||
`offset` | Pagination offset
|
||||
`limit` | Pagination limit
|
||||
|
||||
---
|
||||
|
||||
### `collections.info` - Get a document collection
|
||||
|
||||
Returns detailed information on a document collection.
|
||||
|
||||
#### Arguments
|
||||
|
||||
`https://www.getoutline.com/api/collections.info`
|
||||
|
||||
Parameter | Description
|
||||
------------ | -------------
|
||||
`token` | Authentication token
|
||||
`id` | Collection id
|
||||
|
||||
---
|
||||
|
||||
### `collections.create` - Create a document collection
|
||||
|
||||
Creates a new document collection. Outline supports two types of collections:
|
||||
|
||||
- `atlas` - Structured collection with a navigation tree
|
||||
- `journal` - Chronological collection of documents
|
||||
|
||||
#### Arguments
|
||||
|
||||
`https://www.getoutline.com/api/collections.create`
|
||||
|
||||
Parameter | Description
|
||||
------------ | -------------
|
||||
`token` | Authentication token
|
||||
`name` | Collection name
|
||||
`type` | Collection type. Allowed values: `atlas`, `journal`
|
||||
`description` | _(Optional)_ Short description for the collection
|
||||
|
||||
---
|
||||
|
||||
### `collections.updateNavigationTree` - Organize navigation tree
|
||||
|
||||
Collection navigation can be re-organized by sending a modified version of the navigation tree. This method is available for collections with type `atlas`.
|
||||
|
||||
#### Arguments
|
||||
|
||||
`https://www.getoutline.com/api/collections.updateNavigationTree`
|
||||
|
||||
Parameter | Description
|
||||
------------ | -------------
|
||||
`token` | Authentication token
|
||||
`id` | Collection id
|
||||
`tree` | Modified navigation tree
|
||||
|
||||
---
|
||||
|
||||
### `documents.info` - Get a document
|
||||
|
||||
This method returns information for a document with a specific ID. Following identifiers are allowed:
|
||||
|
||||
- UUID - `id` field of the document
|
||||
- URI identifier - Human readable identifier used in Outline URLs (e.g. `outline-api-i48ZEZc5zjXndcP`)
|
||||
|
||||
#### Arguments
|
||||
|
||||
`https://www.getoutline.com/api/documents.info`
|
||||
|
||||
Parameter | Description
|
||||
------------ | -------------
|
||||
`token` | Authentication token
|
||||
`id` | Document id or URI identifier
|
||||
|
||||
---
|
||||
|
||||
### `documents.search` - Search documents
|
||||
|
||||
This methods allows you to search all of your documents with keywords.
|
||||
|
||||
#### Arguments
|
||||
|
||||
`https://www.getoutline.com/api/documents.search`
|
||||
|
||||
Parameter | Description
|
||||
------------ | -------------
|
||||
`token` | Authentication token
|
||||
`query` | Search query
|
||||
|
||||
---
|
||||
|
||||
### `documents.create` - Create a new document
|
||||
|
||||
This method allows you to publish a new document under an existing collection. If your collection is structured `type: atlas` collection, you can also create sub-documents for other documents with optional `parentDocument` parameter.
|
||||
|
||||
#### Arguments
|
||||
|
||||
`https://www.getoutline.com/api/documents.create`
|
||||
|
||||
Parameter | Description
|
||||
------------ | -------------
|
||||
`token` | Authentication token
|
||||
`collection` | `id` of the collection to which the document is created
|
||||
`title` | Title for the document
|
||||
`text` | Content of the document in Markdown
|
||||
`parentDocument` | _(Optional)_ `id` of the parent document within the collection
|
||||
|
||||
---
|
||||
|
||||
### `documents.delete` - Delete a document
|
||||
|
||||
Delete a document and all of its child documents if any.
|
||||
|
||||
#### Arguments
|
||||
|
||||
`https://www.getoutline.com/api/documents.delete`
|
||||
|
||||
Parameter | Description
|
||||
------------ | -------------
|
||||
`token` | Authentication token
|
||||
`id` | Document id or URI identifier
|
|
@ -1,6 +0,0 @@
|
|||
// @flow
|
||||
import api from './api.md';
|
||||
|
||||
export default {
|
||||
api,
|
||||
};
|
|
@ -2,7 +2,6 @@
|
|||
import React from 'react';
|
||||
import Grid from 'styled-components-grid';
|
||||
import { Helmet } from 'react-helmet';
|
||||
import Flex from '../../shared/components/Flex';
|
||||
|
||||
export default function Pricing() {
|
||||
return (
|
||||
|
@ -13,33 +12,28 @@ export default function Pricing() {
|
|||
<div style={{ maxWidth: '800px', margin: '0 auto' }}>
|
||||
<h1>Outline API</h1>
|
||||
<p>
|
||||
First thing we build for Outline was its API. It's the heart and sole
|
||||
of the service and as developers, it's our mission to make the API as
|
||||
rich and easy to use as possible.
|
||||
First thing we build for Outline was its API. It's the heart and sole of the service and
|
||||
as developers, it's our mission to make the API as rich and easy to use as possible.
|
||||
</p>
|
||||
<p>
|
||||
<i>
|
||||
While Outline is still in public beta, we might make small
|
||||
adjustments, including breaking changes to the API.
|
||||
While Outline is still in public beta, we might make small adjustments, including
|
||||
breaking changes to the API.
|
||||
</i>
|
||||
</p>
|
||||
<h2>Making requests</h2>
|
||||
<p>
|
||||
Outline's API follows simple RPC style conventions where each API
|
||||
endpoint is a method on{' '}
|
||||
<code>https://www.getoutline.com/api/<METHOD></code>. Both{' '}
|
||||
<code>GET</code> and <code>POST</code> methods are supported but it's
|
||||
recommeded that you make all call using <code>POST</code>. Only HTTPS
|
||||
is supported in production.
|
||||
Outline's API follows simple RPC style conventions where each API endpoint is a method on{' '}
|
||||
<code>https://www.getoutline.com/api/<METHOD></code>. Both <code>GET</code> and{' '}
|
||||
<code>POST</code> methods are supported but it's recommeded that you make all call using{' '}
|
||||
<code>POST</code>. Only HTTPS is supported in production.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
For <code>GET</code> requests query string parameters are expected
|
||||
(e.g.
|
||||
<code>/api/document.info?id=...&token=...</code>). When making{' '}
|
||||
<code>POST</code> requests, request parameters are parsed depending on{' '}
|
||||
<code>Content-Type</code> header. To make a call using JSON payload,
|
||||
one must pass <code>Content-Type: application/json</code> header:
|
||||
For <code>GET</code> requests query string parameters are expected (e.g.
|
||||
<code>/api/document.info?id=...&token=...</code>). When making <code>POST</code> requests,
|
||||
request parameters are parsed depending on <code>Content-Type</code> header. To make a
|
||||
call using JSON payload, one must pass <code>Content-Type: application/json</code> header:
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
@ -72,33 +66,30 @@ curl https://www.getoutline.com/api/documents.info?id=outline-api-NTpezNwhUP&tok
|
|||
<h2>Authentication</h2>
|
||||
|
||||
<p>
|
||||
To access private API endpoints, you must provide a valid API key. You
|
||||
can create new API keys in your{' '}
|
||||
<a href={`${process.env.URL}/settings`}>account settings</a>. Be
|
||||
careful when handling your keys as they give access to all of your
|
||||
documents.
|
||||
To access private API endpoints, you must provide a valid API key. You can create new API
|
||||
keys in your <a href={`${process.env.URL}/settings`}>account settings</a>. Be careful when
|
||||
handling your keys as they give access to all of your documents.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
To authenticate with Outline API, you can supply the API key as a
|
||||
header (<code>Authorization: Bearer YOUR_API_KEY</code>) or as part of
|
||||
the payload using <code>token</code> parameter. If you're making{' '}
|
||||
<code>GET</code> requests, header based authentication is recommended
|
||||
so that your keys don't leak into logs.
|
||||
To authenticate with Outline API, you can supply the API key as a header (<code>
|
||||
Authorization: Bearer YOUR_API_KEY
|
||||
</code>) or as part of the payload using <code>token</code> parameter. If you're making{' '}
|
||||
<code>GET</code> requests, header based authentication is recommended so that your keys
|
||||
don't leak into logs.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Some API endpoints allow unauhenticated requests for public resources
|
||||
and they can be called without an API key.
|
||||
Some API endpoints allow unauhenticated requests for public resources and they can be
|
||||
called without an API key.
|
||||
</p>
|
||||
|
||||
<h2>Errors</h2>
|
||||
|
||||
<p>
|
||||
All successful API requests will be returned with <code>200</code>{' '}
|
||||
status code and <code>ok: true</code> in the response payload. If
|
||||
there's an error while making the request, appropriate status code is
|
||||
returned with the <code>error</code> message:
|
||||
All successful API requests will be returned with <code>200</code> status code and{' '}
|
||||
<code>ok: true</code> in the response payload. If there's an error while making the
|
||||
request, appropriate status code is returned with the <code>error</code> message:
|
||||
</p>
|
||||
|
||||
<pre>
|
||||
|
@ -125,46 +116,100 @@ curl https://www.getoutline.com/api/documents.info?id=outline-api-NTpezNwhUP&tok
|
|||
|
||||
<Method method="user.s3Upload" label="Get S3 upload credentials">
|
||||
<Description>
|
||||
You can upload small files and images as part of your documents. All
|
||||
files are stored using Amazon S3. Instead of uploading files to
|
||||
Outline, you need to upload them directly to S3 with special
|
||||
credentials which can be obtained through this endpoint.
|
||||
You can upload small files and images as part of your documents. All files are stored
|
||||
using Amazon S3. Instead of uploading files to Outline, you need to upload them directly
|
||||
to S3 with special credentials which can be obtained through this endpoint.
|
||||
</Description>
|
||||
<Arguments>
|
||||
<Argument
|
||||
id="filename"
|
||||
description="Filename of the uploaded file"
|
||||
required
|
||||
/>
|
||||
<Argument
|
||||
id="kind"
|
||||
description="Mimetype of the document"
|
||||
required
|
||||
/>
|
||||
<Argument
|
||||
id="size"
|
||||
description="Filesize of the document"
|
||||
required
|
||||
/>
|
||||
<Argument id="filename" description="Filename of the uploaded file" required />
|
||||
<Argument id="kind" description="Mimetype of the document" required />
|
||||
<Argument id="size" description="Filesize of the document" required />
|
||||
</Arguments>
|
||||
</Method>
|
||||
|
||||
<Method
|
||||
method="collections.list"
|
||||
label="List your document collections"
|
||||
>
|
||||
<Method method="collections.list" label="List your document collections">
|
||||
<Description>List all your document collections.</Description>
|
||||
<Arguments pagination />
|
||||
</Method>
|
||||
|
||||
<Method method="collections.info" label="Get a document collection">
|
||||
<Description>
|
||||
Returns detailed information on a document collection.
|
||||
</Description>
|
||||
<Description>Returns detailed information on a document collection.</Description>
|
||||
<Arguments>
|
||||
<Argument id="id" description="Collection id" required />
|
||||
</Arguments>
|
||||
</Method>
|
||||
|
||||
<Method method="collections.create" label="Create a document collection">
|
||||
<Description>Creates a new document collection.</Description>
|
||||
<Arguments>
|
||||
<Argument id="name" description="Collection name" required />
|
||||
<Argument id="description" description="Short description for the collection" />
|
||||
</Arguments>
|
||||
</Method>
|
||||
|
||||
<Method method="documents.info" label="Get a document">
|
||||
<Description>
|
||||
<p>
|
||||
This method returns information for a document with a specific ID. Following
|
||||
identifiers are allowed:
|
||||
</p>
|
||||
<ul>
|
||||
<li>UUID - `id` field of the document</li>
|
||||
<li>
|
||||
URI identifier - Human readable identifier used in Outline URLs (e.g.{' '}
|
||||
<code>outline-api-i48ZEZc5zjXndcP</code>)
|
||||
</li>
|
||||
</ul>
|
||||
</Description>
|
||||
<Arguments>
|
||||
<Argument id="id" description="Document id or URI identifier" required />
|
||||
</Arguments>
|
||||
</Method>
|
||||
|
||||
<Method method="documents.search" label="Search documents">
|
||||
<Description>
|
||||
This methods allows you to search all of your documents with keywords.
|
||||
</Description>
|
||||
<Arguments>
|
||||
<Argument id="query" description="Search query" required />
|
||||
</Arguments>
|
||||
</Method>
|
||||
|
||||
<Method method="documents.create" label="Create a new document">
|
||||
<Description>
|
||||
This method allows you to publish a new document under an existing collection. By
|
||||
default a document is set to the parent collection root. If you want to create a
|
||||
subdocument, you can pass <code>parentDocument</code> to set parent document.
|
||||
</Description>
|
||||
<Arguments>
|
||||
<Argument
|
||||
id="collection"
|
||||
description={
|
||||
<span>
|
||||
<code>ID</code> of the collection to which the document is created
|
||||
</span>
|
||||
}
|
||||
required
|
||||
/>
|
||||
<Argument id="title" description="Title for the document" required />
|
||||
<Argument id="text" description="Content of the document in Markdow" required />
|
||||
<Argument
|
||||
id="parentDocument"
|
||||
description={
|
||||
<span>
|
||||
<code>ID</code> of the parent document within the collection
|
||||
</span>
|
||||
}
|
||||
/>
|
||||
</Arguments>
|
||||
</Method>
|
||||
|
||||
<Method method="documents.delete" label="Delete a document">
|
||||
<Description>Delete a document and all of its child documents if any.</Description>
|
||||
<Arguments>
|
||||
<Argument id="id" description="Document id or URI identifier" required />
|
||||
</Arguments>
|
||||
</Method>
|
||||
</div>
|
||||
</Grid>
|
||||
);
|
||||
|
@ -196,9 +241,7 @@ const Method = (props: MethodProps) => {
|
|||
);
|
||||
};
|
||||
|
||||
const Description = (props: { children: React.Element<*> }) => (
|
||||
<p>{props.children}</p>
|
||||
);
|
||||
const Description = (props: { children: React.Element<*> }) => <p>{props.children}</p>;
|
||||
const Arguments = (props: { children: React.Element<*> }) => (
|
||||
<table>
|
||||
<thead>
|
||||
|
|
Reference in New Issue