From 4599e03121a3c993fb4c96dbeaf189028eafd325 Mon Sep 17 00:00:00 2001 From: Tom Moor Date: Sat, 22 Dec 2018 18:24:49 -0800 Subject: [PATCH] Update API docs to new layout --- server/pages/Api.js | 840 ------------------------------- server/pages/Privacy.js | 2 +- server/pages/developers/Api.js | 695 +++++++++++++++++++++++++ server/pages/developers/index.js | 169 +++++++ server/routes.js | 6 +- 5 files changed, 869 insertions(+), 843 deletions(-) delete mode 100644 server/pages/Api.js create mode 100644 server/pages/developers/Api.js create mode 100644 server/pages/developers/index.js diff --git a/server/pages/Api.js b/server/pages/Api.js deleted file mode 100644 index 063aa9dab..000000000 --- a/server/pages/Api.js +++ /dev/null @@ -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 ( - - - Developers - Outline - -
-

Developers

-

Outline is built on an open, best-in-class, API

-
- - - - - - - -

- 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. -

- -

Making requests

-

- Outline’s API follows simple RPC style conventions where each - API endpoint is a method on{' '} - https://www.getoutline.com/api/<METHOD>. Both{' '} - GET and POST methods are supported but - it’s recommeded that you make all call using POST. - Only HTTPS is supported in production. -

- -

- 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: -

- -

- Example POST request: -

- 
-                
-                  {`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"}'
-`}
-                
-
- -

- Example GET request: -

- 
-                
-                  {`curl https://www.getoutline.com/api/documents.info?id=outline-api-NTpezNwhUP&token=API_KEY
-`}
-                
-
- -

Authentication

- -

- To access private API endpoints, you must provide a valid API - key. You can create new API keys in your{' '} - account 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 YOUR_API_KEY) or as - part of the payload using token parameter. If - you’re making GET requests, header based - authentication is recommended so that your keys don’t leak into - logs. -

- -

- 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: -

- - 
-                
-                  {`{
-  "ok": false,
-  "error: "Not Found"
-}
-`}
-                
-
- - - - - - - This method returns the user and team info for the user - identified by the token. - - - - - - List all of the users in the team. - - - - - - This method returns the profile info for the user identified by - the token. - - - - - - - - - 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. - - - - - - - - - - - Promote a user to be a team admin. This endpoint is only - available for admin users. - - - - - - - - - Demote existing team admin if there are more than one as one - admin is always required. This endpoint is only available for - admin users. - - - - - - - - - Admin can suspend users to reduce the number of accounts on - their billing plan or prevent them from accessing documention. - - - - - - - - - Admin can re-active a suspended user. This will update the - billing plan and re-enable their access to the documention. - - - - - - - - List all your document collections. - - - - - - Returns detailed information on a document collection. - - - - - - - - Creates a new document collection. - - - - - - - - - This method allows you to modify already created document. - - - - - - - - - - - Delete a collection and all of its documents. This action can’t - be undone so please be careful. - - - - - - - - List all published documents. - - - - - - - List all your draft documents. - - - - -

- This method returns information for a document with a specific - ID. The following identifiers are allowed: -

-
    -
  • - UUID - id field of the document -
    • -
  • - URI identifier - Human readable identifier used in Outline - URLs (e.g. outline-api-i48ZEZc5zjXndcP) -
    • -
- - - - - - - - - - This methods allows you to search all of your documents with - keywords. - - - - - - - - - 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 parentDocument to set parent document. - - - - ID of the collection to which the document is - created - - } - required - /> - - - - ID of the parent document within the - collection - - } - /> - - true by default. Pass false to - create a draft. - - } - /> - - - - - - This method allows you to modify already created document. - - - - - - - Pass true to publish a draft. - - } - /> - - Pass true to signify an autosave. This skips - creating a revision. - - } - /> - - Pass true to signify the end of an editing - session. This will trigger documents.update hooks. - - } - /> - - - - - - 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. - - - - - - - - - - Delete a document and all of its child documents if any. - - - - - - - - - Get a document with its ID or URL identifier from user’s - collections. - - - - - - - - - Restores a document to a previous revision by creating a new - revision with the contents of the given revisionId. - - - - - - - - - - Pins a document to the collection home. The pinned document is - visible to all members of the team. - - - - - - - - - Unpins a document from the collection home. It will still remain - in the collection itself. - - - - - - - - - Star (favorite) a document for authenticated user. - - - - - - - - - Unstar a starred (favorited) document for authenticated user. - - - - - - - - - Return recently viewed documents for the authenticated user - - - - - - - Return recently starred documents for the authenticated user - - - - - - - Return pinned documents for a collection - - - - - - - Return a specific revision of a document. - - - - - - - - - - Return revisions for a document. Upon each edit, a new revision - is stored. - - - - - - - - - List all your currently shared document links. - - - - - - - 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. - - - - - - - - - Makes the share link inactive so that it can no longer be used - to access the document. - - - - - - - - - - ); -} - -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 ( - - - - - - {children} - - - ); -}; - -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 }) => ( -

{props.children}

-); - -type ArgumentsProps = { - pagination?: boolean, - children?: React.Node | string, -}; - -const Arguments = (props: ArgumentsProps) => ( - - - - - - - - - - - {props.pagination && ( - // $FlowIssue - - )} - {props.children} - -
ArgumentRequiredDescription
-); - -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 ( - -

- {props.method} {props.label} -

-
{description}
- HTTP request & arguments -

- {`${process.env.URL}/api/${props.method}`} -

- {apiArgs} - - ); -}; - -type ArgumentProps = { - id: string, - required?: boolean, - description: React.Node | string, -}; - -const Argument = (props: ArgumentProps) => ( - - - {props.id} - - - {props.required ? 'required' : 'optional'} - - {props.description} - -); -const PaginationArguments = () => [ - , - , -]; diff --git a/server/pages/Privacy.js b/server/pages/Privacy.js index 429e73a12..93ca7846c 100644 --- a/server/pages/Privacy.js +++ b/server/pages/Privacy.js @@ -11,7 +11,7 @@ export default function Privacy() { Privacy Policy -
+

Privacy Policy

How we collect and use your information

diff --git a/server/pages/developers/Api.js b/server/pages/developers/Api.js new file mode 100644 index 000000000..6ce20c1de --- /dev/null +++ b/server/pages/developers/Api.js @@ -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 ( + + + API Reference - Outline + +
+

API Reference

+

Outline is built on an open, best-in-class, API

+
+ + + + + This method returns the user and team info for the user identified + by the token. + + + + + + List all of the users in the team. + + + + + + This method returns the profile info for the user identified by + the token. + + + + + + + + + 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. + + + + + + + + + + + Promote a user to be a team admin. This endpoint is only available + for admin users. + + + + + + + + + Demote existing team admin if there are more than one as one admin + is always required. This endpoint is only available for admin + users. + + + + + + + + + Admin can suspend users to reduce the number of accounts on their + billing plan or prevent them from accessing documention. + + + + + + + + + Admin can re-active a suspended user. This will update the billing + plan and re-enable their access to the documention. + + + + + + + + List all your document collections. + + + + + + Returns detailed information on a document collection. + + + + + + + + Creates a new document collection. + + + + + + + + + This method allows you to modify already created document. + + + + + + + + + + + Delete a collection and all of its documents. This action can’t be + undone so please be careful. + + + + + + + + List all published documents. + + + + + + + List all your draft documents. + + + + +

+ This method returns information for a document with a specific + ID. The following identifiers are allowed: +

+
    +
  • + UUID - id field of the document +
    • +
  • + URI identifier - Human readable identifier used in Outline + URLs (e.g. outline-api-i48ZEZc5zjXndcP) +
    • +
+ + + + + + + + + + This methods allows you to search all of your documents with + keywords. + + + + + + + + + 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{' '} + parentDocument to set parent document. + + + + ID of the collection to which the document is + created + + } + required + /> + + + + ID of the parent document within the collection + + } + /> + + true by default. Pass false to + create a draft. + + } + /> + + + + + + This method allows you to modify already created document. + + + + + + + Pass true to publish a draft. + + } + /> + + Pass true to signify an autosave. This skips + creating a revision. + + } + /> + + Pass true to signify the end of an editing + session. This will trigger documents.update hooks. + + } + /> + + + + + + 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. + + + + + + + + + + Delete a document and all of its child documents if any. + + + + + + + + + Get a document with its ID or URL identifier from user’s + collections. + + + + + + + + + Restores a document to a previous revision by creating a new + revision with the contents of the given revisionId. + + + + + + + + + + Pins a document to the collection home. The pinned document is + visible to all members of the team. + + + + + + + + + Unpins a document from the collection home. It will still remain + in the collection itself. + + + + + + + + + Star (favorite) a document for authenticated user. + + + + + + + + + Unstar a starred (favorited) document for authenticated user. + + + + + + + + + Return recently viewed documents for the authenticated user + + + + + + + Return recently starred documents for the authenticated user + + + + + + Return pinned documents for a collection + + + + + Return a specific revision of a document. + + + + + + + + + Return revisions for a document. Upon each edit, a new revision is + stored. + + + + + + + + + List all your currently shared document links. + + + + + + + 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. + + + + + + + + + Makes the share link inactive so that it can no longer be used to + access the document. + + + + + + + + + ); +} + +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 ( + + + + + + {children} + + + ); +}; + +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 }) => ( +

{props.children}

+); + +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) => ( + + + + + + + + + + + {props.pagination && ( + // $FlowIssue + + )} + {props.children} + +
ArgumentRequiredDescription
+); + +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 ( + + + {props.method} {props.label} + +
{description}
+ HTTP request & arguments +

+ {`${process.env.URL}/api/${props.method}`} +

+ {apiArgs} + + ); +}; + +type ArgumentProps = { + id: string, + required?: boolean, + description: React.Node | string, +}; + +const Argument = (props: ArgumentProps) => ( + + + {props.id} + + + {props.required ? 'required' : 'optional'} + + {props.description} + +); + +const PaginationArguments = () => [ + , + , +]; diff --git a/server/pages/developers/index.js b/server/pages/developers/index.js new file mode 100644 index 000000000..a9afed8dd --- /dev/null +++ b/server/pages/developers/index.js @@ -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 ( + + + Developers - Outline + +
+

Developers

+

Outline is built on an open, best-in-class, API

+
+ + + + + + +

+ 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. +

+ +

Making requests

+

+ Outline’s API follows simple RPC style conventions where each API + endpoint is a method on{' '} + https://www.getoutline.com/api/<METHOD>. Both{' '} + GET and POST methods are supported but + it’s recommeded that you make all call using POST. + Only HTTPS is supported in production. +

+ +

+ 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: +

+ +

+ Example POST request: +

+ 
+              
+                {`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"}'
+`}
+              
+
+ +

+ Example GET request: +

+ 
+              
+                {`curl https://www.getoutline.com/api/documents.info?id=outline-api-NTpezNwhUP&token=API_KEY
+`}
+              
+
+ +

Authentication

+ +

+ To access private API endpoints, you must provide a valid API key. + You can create new API keys in your{' '} + account 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 YOUR_API_KEY) or as + part of the payload using token parameter. If you’re + making GET requests, header based authentication is + recommended so that your keys don’t leak into logs. +

+ +

+ 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: +

+ + 
+              
+                {`{
+  "ok": false,
+  "error: "Not Found"
+}
+`}
+              
+
+ + + + + ); +} + +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; +`; diff --git a/server/routes.js b/server/routes.js index bdf136b0f..303d4b001 100644 --- a/server/routes.js +++ b/server/routes.js @@ -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, )); router.get('/pricing', ctx => renderpage(ctx, )); -router.get('/developers', ctx => renderpage(ctx, )); +router.get('/developers', ctx => renderpage(ctx, )); +router.get('/developers/api', ctx => renderpage(ctx, )); router.get('/privacy', ctx => renderpage(ctx, )); router.get('/integrations/:slug', async ctx => { const slug = ctx.params.slug;