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

Update API docs to new layout

Browse Source
This commit is contained in:
Tom Moor
2018-12-22 18:24:49 -08:00
parent 122fdfa34b
commit 4599e03121
5 changed files with 869 additions and 843 deletions
Download Patch File Download Diff File Expand all files Collapse all files

840
server/pages/Api.js
View File

@@ -1,840 +0,0 @@
// @flow
import * as React from 'react';
import Grid from 'styled-components-grid';
import { Helmet } from 'react-helmet';
import styled from 'styled-components';
import Header from './components/Header';
import Content from './components/Content';
const Container = styled.div`
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: 1em;
padding: 2px 4px;
background: #333;
border-radius: 4px;
color: #fff;
}
}
`;
export default function Pricing() {
return (
<Grid>
<Helmet>
<title>Developers - Outline</title>
</Helmet>
<Header background="#AA34F0">
<h1>Developers</h1>
<p>Outline is built on an open, best-in-class, API</p>
</Header>
<Content>
<Container>
<Grid>
<Grid.Unit
size={{ tablet: 1 / 4 }}
visible={{ mobile: false, tablet: true }}
>
<nav>
<h2>Introduction</h2>
<List>
<li>
<MenuItem href={`#requests`}>Making requests</MenuItem>
</li>
<li>
<MenuItem href={`#authentication`}>Authentication</MenuItem>
</li>
<li>
<MenuItem href={`#errors`}>Errors</MenuItem>
</li>
</List>
</nav>
</Grid.Unit>
<Grid.Unit size={{ tablet: 3 / 4 }}>
<p>
As developers, it’s our mission to make the API as great as
possible. While Outline is still in public beta, we might make
small adjustments, including breaking changes to the API.
</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.
</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>
</Grid.Unit>
</Grid>
<Methods>
<Method method="auth.info" label="Get current auth">
<Description>
This method returns the user and team info for the user
identified by the token.
</Description>
<Arguments />
</Method>
<Method method="users.list" label="List team's users">
<Description>List all of the users in the team.</Description>
<Arguments pagination />
</Method>
<Method method="users.info" label="Get current user">
<Description>
This method returns the profile info for the user identified by
the token.
</Description>
<Arguments>
<Argument id="id" description="Collection id" required />
</Arguments>
</Method>
<Method method="users.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="users.promote" label="Promote a new admin user">
<Description>
Promote a user to be a team admin. This endpoint is only
available for admin users.
</Description>
<Arguments pagination>
<Argument
id="id"
description="User ID to be promoted"
required
/>
</Arguments>
</Method>
<Method method="users.demote" label="Demote existing admin user">
<Description>
Demote existing team admin if there are more than one as one
admin is always required. This endpoint is only available for
admin users.
</Description>
<Arguments pagination>
<Argument
id="id"
description="User ID to be demoted"
required
/>
</Arguments>
</Method>
<Method method="users.suspend" label="Suspend user account">
<Description>
Admin can suspend users to reduce the number of accounts on
their billing plan or prevent them from accessing documention.
</Description>
<Arguments pagination>
<Argument
id="id"
description="User ID to be suspended"
required
/>
</Arguments>
</Method>
<Method
method="users.activate"
label="Activate a suspended user account"
>
<Description>
Admin can re-active a suspended user. This will update the
billing plan and re-enable their access to the documention.
</Description>
<Arguments pagination>
<Argument
id="id"
description="User ID to be activated"
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.list" label="List your documents">
<Description>List all published documents.</Description>
<Arguments pagination>
<Argument
id="collection"
description="Collection ID to filter by"
/>
</Arguments>
</Method>
<Method method="documents.drafts" label="List your draft documents">
<Description>List all your draft documents.</Description>
</Method>
<Method method="documents.info" label="Get a document">
<Description>
<p>
This method returns information for a document with a specific
ID. The 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" />
<Argument id="shareId" description="An active shareId" />
</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>
}
/>
<Argument
id="publish"
description={
<span>
<code>true</code> by default. Pass <code>false</code> to
create a draft.
</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"
/>
<Argument
id="publish"
description={
<span>
Pass <code>true</code> to publish a draft.
</span>
}
/>
<Argument
id="autosave"
description={
<span>
Pass <code>true</code> to signify an autosave. This skips
creating a revision.
</span>
}
/>
<Argument
id="done"
description={
<span>
Pass <code>true</code> to signify the end of an editing
session. This will trigger documents.update hooks.
</span>
}
/>
</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. 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)"
/>
</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.restore"
label="Restore a previous revision"
>
<Description>
Restores a document to a previous revision by creating a new
revision with the contents of the given revisionId.
</Description>
<Arguments>
<Argument
id="id"
description="Document ID or URI identifier"
required
/>
<Argument
id="revisionId"
description="Revision ID to restore to"
required
/>
</Arguments>
</Method>
<Method method="documents.pin" label="Pin a document">
<Description>
Pins a document to the collection home. The pinned document is
visible to all members of the team.
</Description>
<Arguments>
<Argument
id="id"
description="Document ID or URI identifier"
required
/>
</Arguments>
</Method>
<Method method="documents.unpin" label="Unpin a document">
<Description>
Unpins a document from the collection home. It will still remain
in the collection itself.
</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 a starred (favorited) 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.pinned"
label="Get pinned documents for a collection"
>
<Description>
Return pinned documents for a collection
</Description>
<Arguments pagination />
</Method>
<Method
method="documents.revision"
label="Get revision for a document"
>
<Description>
Return a specific revision of a document.
</Description>
<Arguments>
<Argument
id="id"
description="Document ID or URI identifier"
required
/>
<Argument id="revisionId" description="Revision ID" required />
</Arguments>
</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>
<Argument
id="id"
description="Document ID or URI identifier"
required
/>
</Arguments>
</Method>
<Method method="shares.list" label="List shared document links">
<Description>
List all your currently shared document links.
</Description>
<Arguments pagination />
</Method>
<Method method="shares.create" label="Create a share link">
<Description>
Creates a new share link that can be used by anyone to access a
document. If you request multiple shares for the same document
with the same user the same share will be returned.
</Description>
<Arguments>
<Argument id="documentId" description="Document ID" required />
</Arguments>
</Method>
<Method method="shares.revoke" label="Revoke a share link">
<Description>
Makes the share link inactive so that it can no longer be used
to access the document.
</Description>
<Arguments>
<Argument id="id" description="Share ID" required />
</Arguments>
</Method>
</Methods>
</Container>
</Content>
</Grid>
);
}
const MenuItem = styled.a`
display: flex;
align-items: center;
font-size: 16px;
color: ${props => props.theme.text};
`;
const List = styled.ul`
list-style: none;
margin: 0;
padding: 0;
`;
const Methods = (props: { children: React.Node }) => {
const children = React.Children.toArray(props.children);
const methods = children.map(child => child.props.method);
return (
<React.Fragment>
<Grid>
<Grid.Unit
size={{ tablet: 1 / 4 }}
visible={{ mobile: false, tablet: true }}
>
<nav>
<h2>Reference</h2>
<List>
{methods.map(method => (
<li key={method}>
<MenuItem href={`#${method}`}>{method}</MenuItem>
</li>
))}
</List>
</nav>
</Grid.Unit>
<Grid.Unit size={{ tablet: 3 / 4 }}>{children}</Grid.Unit>
</Grid>
</React.Fragment>
);
};
const MethodContainer = styled.div`
margin-bottom: 80px;
`;
const Request = styled.h4`
text-transform: capitalize;
`;
type MethodProps = {
method: string,
label: string,
children: React.Node,
};
const Description = (props: { children: React.Node }) => (
<p>{props.children}</p>
);
type ArgumentsProps = {
pagination?: boolean,
children?: React.Node | 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>
);
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>
);
};
type ArgumentProps = {
id: string,
required?: boolean,
description: React.Node | 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" />,
];

2
server/pages/Privacy.js
View File

@@ -11,7 +11,7 @@ export default function Privacy() {
<Helmet>
<title>Privacy Policy</title>
</Helmet>
<Header>
<Header background="#F4F7FA">
<h1>Privacy Policy</h1>
<p>How we collect and use your information</p>
</Header>

695
server/pages/developers/Api.js Normal file
View File

@@ -0,0 +1,695 @@
// @flow
import * as React from 'react';
import Grid from 'styled-components-grid';
import { Helmet } from 'react-helmet';
import styled from 'styled-components';
import Header from '../components/Header';
import Content from '../components/Content';
export default function Pricing() {
return (
<Grid>
<Helmet>
<title>API Reference - Outline</title>
</Helmet>
<Header background="#AA34F0">
<h1>API Reference</h1>
<p>Outline is built on an open, best-in-class, API</p>
</Header>
<Content>
<Methods>
<Method method="auth.info" label="Get current auth">
<Description>
This method returns the user and team info for the user identified
by the token.
</Description>
<Arguments />
</Method>
<Method method="users.list" label="List team's users">
<Description>List all of the users in the team.</Description>
<Arguments pagination />
</Method>
<Method method="users.info" label="Get current user">
<Description>
This method returns the profile info for the user identified by
the token.
</Description>
<Arguments>
<Argument id="id" description="Collection id" required />
</Arguments>
</Method>
<Method method="users.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="users.promote" label="Promote a new admin user">
<Description>
Promote a user to be a team admin. This endpoint is only available
for admin users.
</Description>
<Arguments pagination>
<Argument id="id" description="User ID to be promoted" required />
</Arguments>
</Method>
<Method method="users.demote" label="Demote existing admin user">
<Description>
Demote existing team admin if there are more than one as one admin
is always required. This endpoint is only available for admin
users.
</Description>
<Arguments pagination>
<Argument id="id" description="User ID to be demoted" required />
</Arguments>
</Method>
<Method method="users.suspend" label="Suspend user account">
<Description>
Admin can suspend users to reduce the number of accounts on their
billing plan or prevent them from accessing documention.
</Description>
<Arguments pagination>
<Argument
id="id"
description="User ID to be suspended"
required
/>
</Arguments>
</Method>
<Method
method="users.activate"
label="Activate a suspended user account"
>
<Description>
Admin can re-active a suspended user. This will update the billing
plan and re-enable their access to the documention.
</Description>
<Arguments pagination>
<Argument
id="id"
description="User ID to be activated"
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.list" label="List your documents">
<Description>List all published documents.</Description>
<Arguments pagination>
<Argument
id="collection"
description="Collection ID to filter by"
/>
</Arguments>
</Method>
<Method method="documents.drafts" label="List your draft documents">
<Description>List all your draft documents.</Description>
</Method>
<Method method="documents.info" label="Get a document">
<Description>
<p>
This method returns information for a document with a specific
ID. The 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" />
<Argument id="shareId" description="An active shareId" />
</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>
}
/>
<Argument
id="publish"
description={
<span>
<Code>true</Code> by default. Pass <Code>false</Code> to
create a draft.
</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"
/>
<Argument
id="publish"
description={
<span>
Pass <Code>true</Code> to publish a draft.
</span>
}
/>
<Argument
id="autosave"
description={
<span>
Pass <Code>true</Code> to signify an autosave. This skips
creating a revision.
</span>
}
/>
<Argument
id="done"
description={
<span>
Pass <Code>true</Code> to signify the end of an editing
session. This will trigger documents.update hooks.
</span>
}
/>
</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. 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)"
/>
</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.restore"
label="Restore a previous revision"
>
<Description>
Restores a document to a previous revision by creating a new
revision with the contents of the given revisionId.
</Description>
<Arguments>
<Argument
id="id"
description="Document ID or URI identifier"
required
/>
<Argument
id="revisionId"
description="Revision ID to restore to"
required
/>
</Arguments>
</Method>
<Method method="documents.pin" label="Pin a document">
<Description>
Pins a document to the collection home. The pinned document is
visible to all members of the team.
</Description>
<Arguments>
<Argument
id="id"
description="Document ID or URI identifier"
required
/>
</Arguments>
</Method>
<Method method="documents.unpin" label="Unpin a document">
<Description>
Unpins a document from the collection home. It will still remain
in the collection itself.
</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 a starred (favorited) 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.pinned"
label="Get pinned documents for a collection"
>
<Description>Return pinned documents for a collection</Description>
<Arguments pagination />
</Method>
<Method
method="documents.revision"
label="Get revision for a document"
>
<Description>Return a specific revision of a document.</Description>
<Arguments>
<Argument
id="id"
description="Document ID or URI identifier"
required
/>
<Argument id="revisionId" description="Revision ID" required />
</Arguments>
</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>
<Argument
id="id"
description="Document ID or URI identifier"
required
/>
</Arguments>
</Method>
<Method method="shares.list" label="List shared document links">
<Description>
List all your currently shared document links.
</Description>
<Arguments pagination />
</Method>
<Method method="shares.create" label="Create a share link">
<Description>
Creates a new share link that can be used by anyone to access a
document. If you request multiple shares for the same document
with the same user the same share will be returned.
</Description>
<Arguments>
<Argument id="documentId" description="Document ID" required />
</Arguments>
</Method>
<Method method="shares.revoke" label="Revoke a share link">
<Description>
Makes the share link inactive so that it can no longer be used to
access the document.
</Description>
<Arguments>
<Argument id="id" description="Share ID" required />
</Arguments>
</Method>
</Methods>
</Content>
</Grid>
);
}
const MenuItem = styled.a`
display: flex;
align-items: center;
font-size: 16px;
color: ${props => props.theme.text};
`;
const List = styled.ul`
list-style: none;
margin: 0;
padding: 0;
`;
const Methods = (props: { children: React.Node }) => {
const children = React.Children.toArray(props.children);
const methods = children.map(child => child.props.method);
return (
<React.Fragment>
<Grid>
<Grid.Unit
size={{ tablet: 1 / 4 }}
visible={{ mobile: false, tablet: true }}
>
<nav>
<h2>Reference</h2>
<List>
{methods.map(method => (
<li key={method}>
<MenuItem href={`#${method}`}>{method}</MenuItem>
</li>
))}
</List>
</nav>
</Grid.Unit>
<Grid.Unit size={{ tablet: 3 / 4 }}>{children}</Grid.Unit>
</Grid>
</React.Fragment>
);
};
const MethodContainer = styled.div`
margin-bottom: 80px;
`;
const Request = styled.h4`
text-transform: capitalize;
`;
type MethodProps = {
method: string,
label: string,
children: React.Node,
};
const Description = (props: { children: React.Node }) => (
<p>{props.children}</p>
);
type ArgumentsProps = {
pagination?: boolean,
children?: React.Node | string,
};
const Table = styled.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;
}
}
`;
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>
);
const Heading = styled.h3`
code {
font-size: 1em;
padding: 2px 4px;
background: #333;
border-radius: 4px;
color: #fff;
}
`;
const Code = styled.code`
font-size: 15px;
`;
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>
<Heading id={props.method}>
<code>{props.method}</code> {props.label}
</Heading>
<div>{description}</div>
<Request>HTTP request & arguments</Request>
<p>
<Code>{`${process.env.URL}/api/${props.method}`}</Code>
</p>
{apiArgs}
</MethodContainer>
);
};
type ArgumentProps = {
id: string,
required?: boolean,
description: React.Node | 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" />,
];

169
server/pages/developers/index.js Normal file
View File

@@ -0,0 +1,169 @@
// @flow
import * as React from 'react';
import Grid from 'styled-components-grid';
import { Helmet } from 'react-helmet';
import styled from 'styled-components';
import Header from '../components/Header';
import Content from '../components/Content';
export default function Pricing() {
return (
<Grid>
<Helmet>
<title>Developers - Outline</title>
</Helmet>
<Header background="#AA34F0">
<h1>Developers</h1>
<p>Outline is built on an open, best-in-class, API</p>
</Header>
<Content>
<Grid>
<Grid.Unit
size={{ tablet: 1 / 4 }}
visible={{ mobile: false, tablet: true }}
>
<nav>
<h2>Introduction</h2>
<List>
<li>
<MenuItem href="#requests">Making requests</MenuItem>
</li>
<li>
<MenuItem href="#authentication">Authentication</MenuItem>
</li>
<li>
<MenuItem href="#errors">Errors</MenuItem>
</li>
</List>
<h2>API</h2>
<List>
<li>
<MenuItem href="/developers/api">Reference</MenuItem>
</li>
</List>
</nav>
</Grid.Unit>
<Grid.Unit size={{ tablet: 3 / 4 }}>
<p>
As developers, it’s our mission to make the API as great as
possible. While Outline is still in public beta, we might make
small adjustments, including breaking changes to the API.
</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.
</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>
</Grid.Unit>
</Grid>
</Content>
</Grid>
);
}
const Pre = styled.pre`
padding: 0.5em 1em;
background: #f9fbfc;
border-radius: 4px;
border: 1px solid #e8ebed;
overflow: scroll;
`;
const Code = styled.code`
font-size: 15px;
`;
const MenuItem = styled.a`
display: flex;
align-items: center;
font-size: 16px;
color: ${props => props.theme.text};
`;
const List = styled.ul`
list-style: none;
margin: 0;
padding: 0;
`;

6
server/routes.js
View File

@@ -23,7 +23,8 @@ import Pricing from './pages/Pricing';
import Integrations from './pages/integrations';
import integrations from './pages/integrations/content';
import Integration from './pages/integrations/Integration';
import Api from './pages/Api';
import Developers from './pages/developers';
import Api from './pages/developers/Api';
import SubdomainSignin from './pages/SubdomainSignin';
const isProduction = process.env.NODE_ENV === 'production';
@@ -63,7 +64,8 @@ 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 />));
router.get('/developers', ctx => renderpage(ctx, <Developers />));
router.get('/developers/api', ctx => renderpage(ctx, <Api />));
router.get('/privacy', ctx => renderpage(ctx, <Privacy />));
router.get('/integrations/:slug', async ctx => {
const slug = ctx.params.slug;