About this Document...

This document is a sample of how I will document a customer's API. The document includes sections of a fictional API for the company VH Enterprises.

VHE API for HTTP

The VHE API v1 is a set of HTTP endpoints that help your application integreate with VHE.

We suggest that you use one of our officially supported SDKs. However, the raw HTTP documentation is helpful if your preferred programming language is not supported, or if you prefer not to use an SDK.

VHE API v1

The VHE API allows developers to work with files in VHE, including advanced functionality like full-text search, thumbnails, and sharing.

Request and Response Formats

In general, the VHE API uses HTTP POST requests with JSON arguments and JSON responses. Request authentication is done via OAuth 2.0 using the Authorization request header or Authorization URL parameter.

The .tag field in an object identifies the subtype of a struct or selected member of a union.

When specifying a Void member of a union, you may supply just the member string in place of the entire tagged union object. For example, when supplying a WriteMode, you can supply just "mode": "add" instead of "mode": {".tag": "add"}}. This shorthand is not allowed for non-Void members. For example, the following is not allowed for a WriteMode, as update is not a Void member: "mode": "update".

RPC endpoints

These endpoints accept arguments as JSON in the request body and return results as JSON in the response body. RPC endpoints are on the api.vheapi.com domain.

Content-upload endpoints

These endpoints accept file content in the request body, so their arguments are instead passed as JSON in the VHE-API-Arg request header or arg URL parameter. These endpoints are on the content.vheapi.com domain.

Content-download endpoints

As with content-upload endpoints, arguments are passed in the VHE-API-Arg request header or arg URL parameter. The response body contains file content, so the result will appear as JSON in the VHE-API-Result response header. These endpoints are also on the content.vheapi.com domain.

These endpoints also support HTTP GET along with ETag-based caching (If-None-Match) and HTTP range requests.

Browser-based JavaScript and CORS pre-flight requests

When browser-based JavaScript code makes a cross-site HTTP request, the browser must sometimes send a "pre-flight" check to make sure the server allows cross-site requests. You can avoid the extra round-trip by ensuring your request meets the CORS definition of a "simple cross-site request".

• Use URL parameters arg and authorization instead of HTTP headers VHE-API-Arg and Authorization.
• Set the Content-Type to "text/plain; charset=vhe-cors-hack" instead of "application/json" or "application/octet-stream".
• Always set the URL parameter reject_cors_preflight=true. This makes it easier to catch cases where your code is unintentionally triggering a pre-flight check.

(More general info about the API... )

Authorization

VHE supports OAuth 2.0 for authorizing API requests. Authorized requests to the API should use an Authorization header with the value Bearer <TOKEN>, where <TOKEN> is an access token obtained through the OAuth flow.

NOTE: OAuth is an authorization protocol, NOT an authentication protocol. VHE should not be used as an identity provider.

/oauth2/authorize

Description

This starts the OAuth 2.0 authorization flow. This isn't an API call—it's the web page that lets the user sign in to VHE and authorize your app. After the user decides whether or not to authorize your app, they will be redirected to the URI specified by redirect_uri.

OAuth 2.0 supports three authorization flows:

• The code flow returns a code via the redirect_uri callback which should then be converted into a bearer token using the /oauth2/token call. This is the recommended flow for apps that are running on a server.
• The PKCE flow is an extension of the code flow that uses dynamically generated codes instead of a secret to perform an OAuth exchange from public clients. The PKCE flow is a newer, more secure alternative to the token (implicit) flow. It is the recommended flow for client-side apps, such as mobile or JavaScript apps.
• [Legacy. We recommend the PKCE flow.] -- The token or implicit grant flow returns the bearer token via the redirect_uri callback, rather than requiring your app to make a second call to a server. This is useful for pure client-side apps, such as mobile apps or JavaScript-based apps.

For more information on the code and token flows, see Section 1.3 of the OAuth 2 spec. For more info on the PKCE extension, see RFC 7636

Your app should send the user to this app authorization page in their system browser, which will display the permissions being granted. If the user isn't already signed in to the VHE website, they will be prompted to do so on this web page. This web page should not be displayed in a web-view. This is in order to maintain compatibilty with the website and to comply with Google's policy against processing their OAuth flow inside a web-view, to support users who sign in to VHE using their Google accounts.

URL Structure

https://www.vhe.com/oauth2/authorize

NOTE: This is the only step that requires an endpoint on www.vhe.com. All other API requests are done via api.vheapi.com, content.vheapi.com, or notify.vheapi.com.

Method

GET

Example

Example: Auth URL for code flow

https://www.vhe.com/oauth2/authorize?client_id=<APP_KEY>&response_type=code

Example: Auth URL for code flow with offline token access type

https://www.vhe.com/oauth2/authorize?client_id=<APP_KEY>&token_access_type=offline&response_type=code

Example: Auth URL for PKCE code flow

https://www.vhe.com/oauth2/authorize?client_id=<APP_KEY>&response_type=code&code_challenge=<CHALLENGE>&code_challenge_method=<METHOD>

Parameters

response_type String The grant type requested, either token or code.

client_id String The app's key, found in the App Console.

redirect_uri String? Where to redirect the user after authorization has completed. This must be the exact URI registered in the App Console, even 'localhost' must be listed if it is used for testing. All redirect URIs must be HTTPS except for localhost URIs. A redirect URI is required for the token flow, but optional for the code flow. If the redirect URI is omitted, the code will be presented directly to the user and they will be invited to enter the information in your app.

scope String? This parameter allows your user to authorize a subset of the scopes selected in the App Console. Multiple scopes are separated by a space. If this parameter is omitted, the authorization page will request all scopes selected on the Permissions tab. Read about scopes in the OAuth Guide.

token_access_type String? If this parameter is set to offline, then the access token payload returned by a successful /oauth2/token call will contain a short-lived access_token and a long-lived refresh_token that can be used to request a new short-lived access token as long as a user's approval remains valid. If set to online then only a short-lived access_token will be returned. If omitted, the response will default to returning a long-lived access_token if they are allowed in the app console. If long-lived access tokens are disabled in the app console, this parameter defaults to online

state String? Up to 500 bytes of arbitrary data that will be passed back to your redirect URI. This parameter should be used to protect against cross-site request forgery (CSRF). See Sections 4.4.1.8 and 4.4.2.5 of the OAuth 2.0 threat model spec.

code_challenge String?(min_length=43, max_length=128) Part of the PKCE flow, the challenge should be an SHA-256 (S256) encoded value of a string that will serve as the code_verifier of the corresponding /oauth2/token call. Can can also be set to plain (plain).

code_challenge_method String? Defines the code challenge method. Can be set to S256 (recommended) or plain.

require_role String? If this parameter is specified, the user will be asked to authorize with a particular type of VHE account, either work for a team account or personal for a personal account. Your app should still verify the type of VHE account after authorization since the user could modify or remove the require_role parameter.

force_reapprove Boolean? Whether or not to force the user to approve the app again if they've already done so. If false (default), a user who has already approved the application may be automatically redirected to the URI specified by redirect_uri. If true, the user will not be automatically redirected and will have to approve the app again.

disable_signup Boolean? When true (default is false) users will not be able to sign up for a VHE account via the authorization page. Instead, the authorization page will show a link to the VHE iOS app in the App Store. This is only intended for use when necessary for compliance with App Store policies.

locale String? If the locale specified is a supported language, VHE will direct users to a translated version of the authorization website. Locale tags should be IETF language tags.

force_reauthentication Boolean? When true (default is false) users will be signed out if they are currently signed in. This will make sure the user is brought to a page where they can create a new account or sign in to another account. This should only be used when there is a definite reason to believe that the user needs to sign in to a new or different account.

Returns

Because /oauth2/authorize is a website, there is no direct return value. However, after the user authorizes your app, they will be sent to your redirect URI. The type of response varies based on the response_type.

Code flow and PKCE flow

These parameters are passed in the query string (after the ? in the URL):

code String The authorization code, which can be used to attain a bearer token by calling /oauth2/token.

state String The state content, if any, originally passed to /oauth2/authorize.

Sample response

[REDIRECT_URI]?code=ABCDEFG&state=[STATE]

Token flow

These parameters are passed in the URL fragment (after the # in the URL).

Note: as fragments, these parameters can be modified by the user and must not be trusted server-side. If any of these fields are being used server-side, please use the PKCE flow, or alternatively using the fields returned from /get_current_account instead.

access_token String A token which can be used to make calls to the VHE API.

token_type String The type of token, which will always be bearer.

account_id String A user's account identifier used by API v2.

team_id String A team's identifier used by API v2.

uid String Deprecated. The API v1 user/team identifier. Please use account_id instead.

state String The state content, if any, originally passed to /oauth2/authorize.

Sample response

[REDIRECT_URI]#access_token=ABCDEFG&token_type=bearer&account_id=dbid%3AAAH4f99T0taONIb-OurWxbNQ6ywGRopQngc&uid=12345&state=[STATE]

Errors

In either flow, if an error occurs, including if the user has chosen not to authorize the app, the following parameters will be included in the redirect URI:

error String An error code per Section 4.1.2.1 of the OAuth 2.0 spec.

error_description String A user-friendly description of the error that occurred.

state String The state content, if any, originally passed to /oauth2/authorize.

/oauth2/token

Description

This endpoint only applies to apps using the authorization code flow. An app calls this endpoint to acquire a bearer token once the user has authorized the app.

Calls to /oauth2/token need to be authenticated using the apps's key and secret. These can either be passed as application/x-www-form-urlencoded POST parameters (see parameters below) or via HTTP basic authentication. If basic authentication is used, the app key should be provided as the username, and the app secret should be provided as the password.

URL Structure

https://api.vheapi.com/oauth2/token

Method

POST

Example

Example: access token request in code flow

curl https://api.vhe.com/oauth2/token \
                  -d code=<AUTHORIZATION_CODE> \
                  -d grant_type=authorization_code \
                  -d redirect_uri=<REDIRECT_URI> \
                  -u <APP_KEY>:<APP_SECRET>
              

Example: refresh token request

curl https://api.vhe.com/oauth2/token \
                  -d grant_type=refresh_token \
                  -d refresh_token=<REFRESH_TOKEN> \
                  -u <APP_KEY>:<APP_SECRET>

Example: PKCE code flow token request

curl https://api.vhe.com/oauth2/token \
                  -d code=<AUTHORIZATION_CODE> \
                  -d grant_type=authorization_code \
                  -d redirect_uri=<REDIRECT_URI> \
                  -d code_verifier=<VERIFICATION_CODE> \
                  -d client_id=<APP_KEY>

Parameters

code String The code acquired by directing users to /oauth2/authorize?response_type=code.

grant_type String The grant type, which must be authorization_code for completing a code flow or refresh_token for using a refresh token to get a new access token.

refresh_token String? A unique, long-lived token that can be used to request new short-lived access tokens without direct interaction from a user in your app.

client_id String? If credentials are passed in POST parameters, this parameter should be present and should be the app's key (found in the App Console).

client_secret String? If credentials are passed in POST parameters, this parameter should be present and should be the app's secret.

redirect_uri String? The redirect URI used to receive the authorization code from /oauth2/authorize, if provided. Only used to validate it matches the redirect URI supplied to /oauth2/authorize for the current authorization code. It is not used to redirect again.

code_verifier String?(min_length=43, max_length=128) The client-generated string used to verify the encrypted code_challenge used in the Authorization URL.

Returns

A JSON-encoded dictionary including an access token (access_token), the length of time it's valid (expires_in), token type (token_type), the permission set applied to the token (scope), an API v2 user ID (account_id), or if team-linked, an API v2 team ID (team_id) instead. If the token_access_type was set to offline when calling /oauth2/authorize, then response will include a refresh token (refresh_token). The API v1 identifier value (uid) is deprecated and should no longer be used. The token type will always be "bearer".

Sample response

Example: short-lived token

{
                "access_token": "sl.AbX9y6Fe3AuH5o66-gmJpR032jwAwQPIVVzWXZNkdzcYT02akC2de219dZi6gxYPVnYPrpvISRSf9lxKWJzYLjtMPH-d9fo_0gXex7X37VIvpty4-G8f4-WX45AcEPfRnJJDwzv-",
                "expires_in": "13220",
                "token_type": "bearer",
                "scope": "account_info.read files.content.read files.content.write files.metadata.read",
                "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                "uid": "12345",
              }

Example: short-lived "offline" access token

{
                "access_token": "sl.abcd1234efg",
                "expires_in": "13220",
                "token_type": "bearer",
                "scope": "account_info.read files.content.read files.content.write files.metadata.read",
                "refresh_token": "AAEVvIKp9ApA9wkdE",
                "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                "uid": "12345",
              }

Example: legacy token

{
                "access_token": "ABCDEFG",
                "token_type": "bearer",
                "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
                "uid": "12345",
              }

{
            "error_summary": "invalid_access_token/...",
            "error": {
                ".tag": "invalid_access_token"
            }
        }

{
            "error_summary": "invalid_select_user/...",
            "error": {
                ".tag": "invalid_select_user"
            }
        }

{
            "error_summary": "invalid_select_admin/...",
            "error": {
                ".tag": "invalid_select_admin"
            }
        }

{
            "error_summary": "user_suspended/...",
            "error": {
                ".tag": "user_suspended"
            }
        }

{
            "error_summary": "expired_access_token/...",
            "error": {
                ".tag": "expired_access_token"
            }
        }

{
            "error_summary": "route_access_denied/...",
            "error": {
                ".tag": "route_access_denied"
            }
        }

{
            "error_summary": "other/...",
            "error": {
                ".tag": "other"
            }
        }

REST API calls

account

/set_profile_photo

auth

/token/from_oauth1

/token/revoke