yuuza/outline
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

more docs

Browse Source
This commit is contained in:
Jori Lallo
2017-11-19 17:55:04 -08:00
parent e82654ab7f
commit b4f7d9f61d
1 changed files with 310 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

379
server/pages/Api.js
View File

@@ -2,38 +2,92 @@
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</title>
<title>Developer API - Outline</title>
</Helmet>
<div style={{ maxWidth: '800px', margin: '0 auto' }}>
<Container>
<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/&lt;METHOD&gt;</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/&lt;METHOD&gt;</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>
@@ -41,8 +95,7 @@ export default function Pricing() {
</p>
<pre>
<code>
{`
curl https://www.getoutline.com/api/documents.info
{`curl https://www.getoutline.com/api/documents.info
-X POST
-H 'authorization: Bearer API_KEY'
-H 'content-type: application/json'
@@ -57,8 +110,7 @@ curl https://www.getoutline.com/api/documents.info
</p>
<pre>
<code>
{`
curl https://www.getoutline.com/api/documents.info?id=outline-api-NTpezNwhUP&token=API_KEY
{`curl https://www.getoutline.com/api/documents.info?id=outline-api-NTpezNwhUP&token=API_KEY
`}
</code>
</pre>
@@ -66,36 +118,38 @@ 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>
<code>
{`
{
{`{
"ok": false,
"error: "Not Found"
}
@@ -116,59 +170,90 @@ 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">
<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" />
<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:
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>)
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 />
<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.
This methods allows you to search all of your documents with
keywords.
</Description>
<Arguments>
<Argument id="query" description="Search query" required />
@@ -177,22 +262,32 @@ curl https://www.getoutline.com/api/documents.info?id=outline-api-NTpezNwhUP&tok
<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.
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
<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="title"
description="Title for the document"
required
/>
<Argument
id="text"
description="Content of the document in Markdow"
required
/>
<Argument
id="parentDocument"
description={
@@ -204,17 +299,141 @@ curl https://www.getoutline.com/api/documents.info?id=outline-api-NTpezNwhUP&tok
</Arguments>
</Method>
<Method method="documents.delete" label="Delete a document">
<Description>Delete a document and all of its child documents if any.</Description>
<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="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>
</div>
<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>
</Container>
</Grid>
);
}
const MethodContainer = styled.div`
margin-bottom: 40px;
`;
const Request = styled.h4`
text-transform: capitalize;
`;
type MethodProps = {
method: string,
label: string,
@@ -227,22 +446,30 @@ const Method = (props: MethodProps) => {
const apiArgs = children.find(child => child.type === Arguments);
return (
<div>
<MethodContainer>
<h3>
<code>{props.method}</code> - {props.label}
</h3>
<div>{description}</div>
<h4>Arguments</h4>
<Request>HTTP request & arguments</Request>
<p>
<code>{`${process.env.URL}/api/${props.method}`}</code>
</p>
{apiArgs}
</div>
</MethodContainer>
);
};
const Description = (props: { children: React.Element<*> }) => <p>{props.children}</p>;
const Arguments = (props: { children: React.Element<*> }) => (
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>
@@ -253,15 +480,29 @@ const Arguments = (props: { children: React.Element<*> }) => (
</thead>
<tbody>
<Argument id="token" description="Authentication token" required />
{props.pagination && <PaginationArguments />}
{props.pagination && (
// $FlowIssue
<PaginationArguments />
)}
{props.children}
</tbody>
</table>
);
const Argument = (props: { children: React.Element<*> }) => (
type ArgumentProps = {
id: string,
required?: boolean,
description: React.Element<*> | string,
};
const Argument = (props: ArgumentProps) => (
<tr>
<td>{props.id}</td>
<td>{props.required ? 'required' : 'optional'}</td>
<td>
<code>{props.id}</code>
</td>
<td>
<i>{props.required ? 'required' : 'optional'}</i>
</td>
<td>{props.description}</td>
</tr>
);