Merge pull request #414 from outline/jori/public-api-doc
Public api doc
This commit is contained in:
Jori Lallo
GitHub
559
server/pages/Api.js
Normal file
559
server/pages/Api.js
Normal file
@@ -0,0 +1,559 @@
|
||||
// @flow
|
||||
import React from 'react';
|
||||
import Grid from 'styled-components-grid';
|
||||
import { Helmet } from 'react-helmet';
|
||||
import styled from 'styled-components';
|
||||
|
||||
const Container = styled.div`
|
||||
max-width: 720px;
|
||||
margin: 0 auto;
|
||||
|
||||
pre {
|
||||
padding: 0.5em 1em;
|
||||
background: #f9fbfc;
|
||||
border-radius: 4px;
|
||||
border: 1px solid #e8ebed;
|
||||
overflow: scroll;
|
||||
}
|
||||
|
||||
code {
|
||||
font-size: 15px;
|
||||
}
|
||||
|
||||
table {
|
||||
border-collapse: collapse;
|
||||
|
||||
thead {
|
||||
td {
|
||||
padding: 5px 12px 5px 0;
|
||||
border-bottom: 1px solid #ddd;
|
||||
vertical-align: bottom;
|
||||
font-weight: 500;
|
||||
}
|
||||
}
|
||||
|
||||
tbody,
|
||||
thead {
|
||||
td {
|
||||
padding: 5px 12px 5px 0;
|
||||
}
|
||||
|
||||
td:last-child {
|
||||
width: 100%;
|
||||
padding-right: 0;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
h3 {
|
||||
code {
|
||||
font-size: 1.08em;
|
||||
}
|
||||
}
|
||||
`;
|
||||
|
||||
export default function Pricing() {
|
||||
return (
|
||||
<Grid>
|
||||
<Helmet>
|
||||
<title>Developer API - Outline</title>
|
||||
</Helmet>
|
||||
<Container>
|
||||
<h1>Outline API</h1>
|
||||
<p>
|
||||
First thing we build for Outline was its API. It’s the heart and soul
|
||||
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.
|
||||
</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.
|
||||
</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:
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<strong>Example POST request:</strong>
|
||||
</p>
|
||||
<pre>
|
||||
<code>
|
||||
{`curl https://www.getoutline.com/api/documents.info
|
||||
-X POST
|
||||
-H 'authorization: Bearer API_KEY'
|
||||
-H 'content-type: application/json'
|
||||
-H 'accept: application/json'
|
||||
-d '{"id": "outline-api-NTpezNwhUP"}'
|
||||
`}
|
||||
</code>
|
||||
</pre>
|
||||
|
||||
<p>
|
||||
<strong>Example GET request:</strong>
|
||||
</p>
|
||||
<pre>
|
||||
<code>
|
||||
{`curl https://www.getoutline.com/api/documents.info?id=outline-api-NTpezNwhUP&token=API_KEY
|
||||
`}
|
||||
</code>
|
||||
</pre>
|
||||
|
||||
<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.
|
||||
</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.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
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:
|
||||
</p>
|
||||
|
||||
<pre>
|
||||
<code>
|
||||
{`{
|
||||
"ok": false,
|
||||
"error: "Not Found"
|
||||
}
|
||||
`}
|
||||
</code>
|
||||
</pre>
|
||||
|
||||
<h2>Methods</h2>
|
||||
<Methods>
|
||||
<Method method="user.info" label="Get current user">
|
||||
<Description>
|
||||
This method returns the information for currently logged in user.
|
||||
</Description>
|
||||
<Arguments>
|
||||
<Argument id="id" description="Collection id" required />
|
||||
</Arguments>
|
||||
</Method>
|
||||
|
||||
<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.
|
||||
</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
|
||||
/>
|
||||
</Arguments>
|
||||
</Method>
|
||||
|
||||
<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>
|
||||
<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="collections.update" label="Update a collection">
|
||||
<Description>
|
||||
This method allows you to modify already created document.
|
||||
</Description>
|
||||
<Arguments>
|
||||
<Argument id="id" description="Collection ID" required />
|
||||
<Argument id="name" description="Name for the collection" />
|
||||
<Argument
|
||||
id="color"
|
||||
description="Collection color in hex form (e.g. #E1E1E1)"
|
||||
/>
|
||||
</Arguments>
|
||||
</Method>
|
||||
|
||||
<Method method="collections.delete" label="Delete a collection">
|
||||
<Description>
|
||||
Delete a collection and all of its documents. This action can`t be
|
||||
undone so please be careful.
|
||||
</Description>
|
||||
<Arguments>
|
||||
<Argument id="id" description="Collection ID" required />
|
||||
</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 - <code>id</code> 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.update" label="Update a document">
|
||||
<Description>
|
||||
This method allows you to modify already created document.
|
||||
</Description>
|
||||
<Arguments>
|
||||
<Argument
|
||||
id="id"
|
||||
description="Document id or URI identifier"
|
||||
required
|
||||
/>
|
||||
<Argument id="title" description="Title for the document" />
|
||||
<Argument
|
||||
id="text"
|
||||
description="Content of the document in Markdown"
|
||||
/>
|
||||
</Arguments>
|
||||
</Method>
|
||||
|
||||
<Method method="documents.move" label="Move document in a collection">
|
||||
<Description>
|
||||
Move a document into a new location inside the collection. This is
|
||||
easily done by defining the parent document ID and optional index.
|
||||
If no parent document is provided, the document will be moved to
|
||||
the collection root.
|
||||
</Description>
|
||||
<Arguments>
|
||||
<Argument
|
||||
id="id"
|
||||
description="Document id or URI identifier"
|
||||
required
|
||||
/>
|
||||
<Argument
|
||||
id="parentDocument"
|
||||
description="ID of the new parent document (if any)"
|
||||
/>
|
||||
<Argument id="index" description="Index of the new location" />
|
||||
</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>
|
||||
|
||||
<Method method="documents.info" label="Get a document">
|
||||
<Description>
|
||||
Get a document with its ID or URL identifier from user’s
|
||||
collections.
|
||||
</Description>
|
||||
<Arguments>
|
||||
<Argument
|
||||
id="id"
|
||||
description="Document id or URI identifier"
|
||||
required
|
||||
/>
|
||||
</Arguments>
|
||||
</Method>
|
||||
|
||||
<Method method="documents.star" label="Star a document">
|
||||
<Description>
|
||||
Star (favorite) a document for authenticated user.
|
||||
</Description>
|
||||
<Arguments>
|
||||
<Argument
|
||||
id="id"
|
||||
description="Document id or URI identifier"
|
||||
required
|
||||
/>
|
||||
</Arguments>
|
||||
</Method>
|
||||
|
||||
<Method method="documents.unstar" label="Unstar a document">
|
||||
<Description>
|
||||
Unstar as starred (favorited) a document for authenticated user.
|
||||
</Description>
|
||||
<Arguments>
|
||||
<Argument
|
||||
id="id"
|
||||
description="Document id or URI identifier"
|
||||
required
|
||||
/>
|
||||
</Arguments>
|
||||
</Method>
|
||||
|
||||
<Method
|
||||
method="documents.viewed"
|
||||
label="Get recently viewed document for user"
|
||||
>
|
||||
<Description>
|
||||
Return recently viewed documents for the authenticated user
|
||||
</Description>
|
||||
<Arguments pagination />
|
||||
</Method>
|
||||
|
||||
<Method
|
||||
method="documents.starred"
|
||||
label="Get recently starred document for user"
|
||||
>
|
||||
<Description>
|
||||
Return recently starred documents for the authenticated user
|
||||
</Description>
|
||||
<Arguments pagination />
|
||||
</Method>
|
||||
|
||||
<Method
|
||||
method="documents.revisions"
|
||||
label="Get revisions for a document"
|
||||
>
|
||||
<Description>
|
||||
Return revisions for a document. Upon each edit, a new revision is
|
||||
stored.
|
||||
</Description>
|
||||
<Arguments pagination />
|
||||
</Method>
|
||||
</Methods>
|
||||
</Container>
|
||||
</Grid>
|
||||
);
|
||||
}
|
||||
|
||||
const MethodList = styled.ul`
|
||||
margin-bottom: 80px;
|
||||
`;
|
||||
|
||||
const Methods = (props: { children: React.Element<*> }) => {
|
||||
const children = React.Children.toArray(props.children);
|
||||
const methods = children.map(child => child.props.method);
|
||||
|
||||
return (
|
||||
<div>
|
||||
<MethodList>
|
||||
{methods.map(method => (
|
||||
<li key={method}>
|
||||
<a href={`#${method}`}>{method}</a>
|
||||
</li>
|
||||
))}
|
||||
</MethodList>
|
||||
{children}
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
||||
const MethodContainer = styled.div`
|
||||
margin-bottom: 80px;
|
||||
`;
|
||||
|
||||
const Request = styled.h4`
|
||||
text-transform: capitalize;
|
||||
`;
|
||||
|
||||
type MethodProps = {
|
||||
method: string,
|
||||
label: string,
|
||||
children: React.Element<*>,
|
||||
};
|
||||
|
||||
const Method = (props: MethodProps) => {
|
||||
const children = React.Children.toArray(props.children);
|
||||
const description = children.find(child => child.type === Description);
|
||||
const apiArgs = children.find(child => child.type === Arguments);
|
||||
|
||||
return (
|
||||
<MethodContainer>
|
||||
<h3 id={props.method}>
|
||||
<code>{props.method}</code> - {props.label}
|
||||
</h3>
|
||||
<div>{description}</div>
|
||||
<Request>HTTP request & arguments</Request>
|
||||
<p>
|
||||
<code>{`${process.env.URL}/api/${props.method}`}</code>
|
||||
</p>
|
||||
{apiArgs}
|
||||
</MethodContainer>
|
||||
);
|
||||
};
|
||||
|
||||
const Description = (props: { children: React.Element<*> }) => (
|
||||
<p>{props.children}</p>
|
||||
);
|
||||
|
||||
type ArgumentsProps = {
|
||||
pagination?: boolean,
|
||||
children?: React.Element<*> | string,
|
||||
};
|
||||
|
||||
const Arguments = (props: ArgumentsProps) => (
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<td>Argument</td>
|
||||
<td>Required</td>
|
||||
<td>Description</td>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<Argument id="token" description="Authentication token" required />
|
||||
{props.pagination && (
|
||||
// $FlowIssue
|
||||
<PaginationArguments />
|
||||
)}
|
||||
{props.children}
|
||||
</tbody>
|
||||
</table>
|
||||
);
|
||||
|
||||
type ArgumentProps = {
|
||||
id: string,
|
||||
required?: boolean,
|
||||
description: React.Element<*> | string,
|
||||
};
|
||||
|
||||
const Argument = (props: ArgumentProps) => (
|
||||
<tr>
|
||||
<td>
|
||||
<code>{props.id}</code>
|
||||
</td>
|
||||
<td>
|
||||
<i>{props.required ? 'required' : 'optional'}</i>
|
||||
</td>
|
||||
<td>{props.description}</td>
|
||||
</tr>
|
||||
);
|
||||
const PaginationArguments = () => [
|
||||
<Argument id="offset" description="Pagination offset" />,
|
||||
<Argument id="limit" description="Pagination limit" />,
|
||||
];
|
||||
@@ -12,6 +12,7 @@ import renderpage from './utils/renderpage';
|
||||
import Home from './pages/Home';
|
||||
import About from './pages/About';
|
||||
import Pricing from './pages/Pricing';
|
||||
import Api from './pages/Api';
|
||||
|
||||
const isProduction = process.env.NODE_ENV === 'production';
|
||||
const koa = new Koa();
|
||||
@@ -46,6 +47,7 @@ if (process.env.NODE_ENV === 'production') {
|
||||
// static pages
|
||||
router.get('/about', ctx => renderpage(ctx, <About />));
|
||||
router.get('/pricing', ctx => renderpage(ctx, <Pricing />));
|
||||
router.get('/developers', ctx => renderpage(ctx, <Api />));
|
||||
|
||||
// home page
|
||||
router.get('/', async ctx => {
|
||||
|
||||
Reference in New Issue
Block a user