Embed icon

How to host Apiary documentation on your subdomain using Embed

With a simple JavaScript you can embed and customize your API Project on your domain.

Your own domain

Your own domain

Host Interactive API Documentation on your domain, customize its features and placement.

Your branding

Your branding

With powerful theming options, you can customize the look and feel of the docs.

Private embed

Private embed

For custom 3rd party integrations you can also take advantage of short-lived tokens for embedding.

Apiary Embed docs comes with a single integration and JavaScript API.

This way, you can show your always up-to-date API Documentation on your developer portal, styled with your colors and custom font themes.

Embed documentation comes with an Interactive API Documentation, Mock server, Code examples and more.

1
Paste script into your page

You can place this is before </body> tag.

<script src="https://api.apiary.io/seeds/embed.js"></script>

2
Generate embed code

3
Read Apiary Embed API reference

Apiary Embed API Reference

Apiary Embed allows you to embed API Documentation on your domain, anywhere into your page and with your options and theme. It is a JavaScript file, that after loading into the page exposes a single Apiary object.

Basic options

Specify API Project

Basic use of Apiary Embed needs only a single option: which project to show.

var embed = new Apiary.Embed({
  subdomain: 'pollsapi'
});

Use subdomain option, where subdomain is API Project subdomain, that can be changed in the API Project settings.

Changing API Project subdomain

When you change subdomain in the project settings, you also need to update the embed code.

Note

Customers integrating with Apiary over Integration API can use uuid instead of subdomain. uuid is not affected by subdomain changes. This integration also allows for embedding of private API Projects with short-lived scoped tokens.

Specify the HTML element for the embed

By default, embed takes over the whole browser viewport. You can control position of the embed by specifying the element option as a DOM selector e.g. #my-embed or div.my-embed. Embed will respect the dimensions of the element.

<div id="embedHere"></div>
<script>
var embed = new Apiary.Embed({
  subdomain: 'pollsapi',
  element: '#embedHere'
});
</script>

Alternatively, you can also add a header for a full-screen embed. Just specify the DOM selector for you header and embed will load it on top of it.

<header id="customHeader">My Logo</header>
<script>
var embed = new Apiary.Embed({
  subdomain: 'pollsapi',
  header: '#customHeader'
});
</script>
Note

It’s not possible to use the header option in conjunction with the element option.

Preferences

preferences object allows you to control behavior of API Documentation.

var embed = new Apiary.Embed({
  subdomain: 'pollsapi',
  preferences: { // Defaults, all optional
    console: true, // Allow console, set to `false` to disable
    collapseMachineColumnByDefault: false, // Collapse the machine column by default
    displayUriParametersInHumanColumn: false, // Display URI parameters
    displayHttpMethods: false, // Display names of HTTP methods
    fluidHumanColumn: false, // Human column takes 100% width
    permalinks: false, // Allow linking into the embedded API Project
    defaultHost: 'mock'
  }
});

Setting permalinks option to true will enable deep linking into embed docs. It does it by adding fragments with hash to the URL e.g. #/introduction/media-types. Don’t enable it if your application is using location hash for something else (like navigation in any JavaScript Single Page Application). More details about permalinks in the Interactive Documentation.

Modifying hosts

Available hosts are mock, proxy and production. You can read more about these hosts used in the Interactive Documentation.

Changing default host

You can change defaultHost for any of the available hosts. If production is not available because you didn’t provide HOST in your API Blueprint Embed will fallback to mock.

Modifying available hosts

Use hosts array to specify available hosts:

var embed = new Apiary.Embed({
  subdomain: 'pollsapi',
  preferences: {
    defaultHost: 'production'
  },
  hosts: [
    'proxy',
    'production'
  ]
});

Code examples

Hiding code example languages

With codeExamples option you can control which code examples will be shown, by default, all are allowed:

var embed = new Apiary.Embed({
  subdomain: 'pollsapi',
  codeExamples: {
    cUrl: true, // cURL
    javaScript: true, // JavaScript
    nodeJs: true, // Node.js
    python: true, // Python
    php: true, // PHP
    ruby: true, // Ruby
    c: true, // C#
    visualBasic: true, // Visual Basic
    groovy: true, // Groovy
    objectiveC: true, // ObjectiveC
    java: true, // Java
    go: true, // Go
    perl: true, // Perl
    swift: true // Swift
  }
});

Enabling only some languages

At the same time, you can also choose to whitelist only some code examples:

var embed = new Apiary.Embed({
  subdomain: 'pollsapi',
  codeExamples: [ // Allows only Go and Swift code examples
    'go',
    'swift'
  ]
});

Apiary Embed - whitelist code examples

Adding a code examples language

It’s possible to add a custom code example langugage.

var embed = new Apiary.Embed({
  subdomain: 'pollsapi'
});

embed.addCodeExample('My JavaScript', function(templateData) {
  var output = 'var Request = new XMLHttpRequest();\n';
  output += 'Request.open(' + templateData.method + ', ' + templateData.uri + ');\n';

  if (this.hasHeaders()) {
    templateData.headers.forEach(function (header) {
      output += 'Request.setRequestHeader(' + header.key + ', ' + header.value + ');\n';
    });
  }

  output += 'Request.onreadystatechange = function () {\n';
  output += '  if (this.readyState === 4) {\n';
  output += '    console.log("Body:", this.responseText);\n';
  output += '  }\n';
  output += '};\n';
  output += 'Request.send(JSON.stringify(' + (templateData.body || undefined) + '));';

  return output;
});

Template data reference

Property Example value
method POST
uri /users/123
uriTemplate /users/{id}
url https://api.google.com:9000/users/123
urlTemplate https://api.google.com:9000/users/{id}
host api.google.com:9000
hostname api.google.com
protocol https://
fragment introduction
hash #introduction
port 9000
query foo=bar
search ?foo=bar
headers [ { key: 'Content-Type', value: 'application/json' }, … ]
headers[].key Content-Type
headers[].value application/json
body { name: 'Nancy Musgrove', … }

Helper functions

Available under this inside the function.

  • General
    • hasBody()
    • hasHeaders()
  • Content Type
    • isJson()
    • isHtml()
    • isPlain()
    • isBinary()
    • isForm()
    • isXml()
  • HTTP Method
    • isConnect()
    • isCopy()
    • isDelete()
    • isGet()
    • isHead()
    • isLock()
    • isMkcol()
    • isMove()
    • isOptions()
    • isPatch()
    • isPost()
    • isProppatch()
    • isPut()
    • isTrace()
    • isUnlock()
    • isUpdate()

Custom fonts

customFonts option is used for loading 3rd party fonts into Apiary Embed. These fonts can be then applied with theme option - more on theme.

Loading self-hosted fonts

Use absolute URLs to load fonts. If possible, supply multiple formats for better cross-browser compatibility - woff format should cover +90% of users.

var embed = new Apiary.Embed({
  subdomain: 'pollsapi',
  customFonts: {
    families: [
      {
        name: 'Proxima Nova',
        style: 'normal',
        weight: 200,
        formats: [
          {
            format: 'woff',
            url: 'https://mycdn.com/fonts/proxima-nova/light.woff'
          },
          {
            format: 'truetype',
            url: 'https://mycdn.com/fonts/proxima-nova/light.ttf'
          }
        ]
      }
    ]
  },
  theme: {
    fontFamily: 'Open Sans'
  }
});

Loading Google Fonts

This example adds an Ubuntu from Google Fonts and applies it with theme.

var embed = new Apiary.Embed({
  subdomain: 'pollsapi',
  customFonts: {
    googleFonts: 'https://fonts.googleapis.com/css?family=Ubuntu'
  },
  theme: {
    fontFamily: 'Ubuntu'
  }
});
Note

Always make sure to use the HTTPS link instead of the HTTP one offered by default.

Loading Typekit

var embed = new Apiary.Embed({
  subdomain: 'pollsapi',
  customFonts: {
    typekit: {
      kitId: '<KIT-ID>'
    }
  },
  theme: {
    fontFamily: 'Grafolita Script'
  }
});
Note

Make sure to allow jsapi.apiary.io domain.

Theming

For theming your documentation, we expose a JSON tree of objects/elements to which you can assign CSS properties.

How to

Targetting elements

You always need to address a full path to the element you want to style - e.g.

var embed = new Apiary.Embed({
  subdomain: 'pollsapi',
  theme: {
    machineColumn: { // To change color of a title in Machine Column
      content: {
        blankState: {
          title: {
            color: '#85144b'
          }
        }
      }
    }
  }
});

Elements with a state

Elements starting with $ describe a state - like $selected or $hover. Or in some cases HTTP methods like $get or $put.

Elements

Below you can find list of available styling elements - there are 3 main parts: Table of Contents (left), Human Column (middle) and Machine Column (right).

Table of Contents


tableOfContents
- section
-- title
--- text
---- $hover
-- item
--- text
--- subitems
---- subitem
----- subitem
------ text
------ $hover
------ $selected
------ $selected$hover

Human Column


humanColumn
- wrapper
- content
-- apiName
--- $hover
-- section
--- title
---- $hover
---- text
---- apiDescription
---- Section Description ↝

Machine Column


machineColumn
- Code examples ↝
- content
-- URI Parameters ↝
-- blankState
--- title
--- text
--- link
-- breadCrumbs
--- container
--- line
--- resourceGroup
--- resource
--- action
--- slash
-- destination
--- container
---- method
----- $connect
----- $copy
----- $delete
----- $get
----- $head
----- $lock
----- $mkcol
----- $move
----- $options
----- $patch
----- $post
----- $proppatch
----- $put
----- $trace
----- $unlock
----- $update
---- protocol
---- host
---- uriTemplate
----- container
------ slash
------ variable
------ queryVariableKey
------ queryVariableValue
-- title
--- text
-- request
--- name
--- description
---- Section Description ↝
--- controls
---- hosts
---- codeExamples
---- spacer
---- tryButton
-- response
--- name
--- statusCode
--- description
---- Section Description ↝
- console
-- blankSlate
--- title
--- text
--- link
-- breadcrumbs
--- line
--- resourceGroup
--- resource
--- action
--- slash
-- form
--- destination
---- container
---- method
----- $connect
----- $copy
----- $delete
----- $get
----- $head
----- $lock
----- $mkcol
----- $move
----- $options
----- $patch
----- $post
----- $proppatch
----- $put
----- $trace
----- $unlock
----- $update
---- protocol
---- host
---- uriTemplate
----- container
------ slash
------ variable
------ queryVariableKey
------ queryVariableValue
--- tabs
---- buttonGroup
----- item
------ $selected
--- tab
--- parameters
---- list
----- parameter
------ column
------ nameColumn
------ valueColumn
------ name
------ value
--- body
---- textarea
--- headers
---- list
----- header
------ key
------- input
------ value
------- input
---- addHeaderButton
----- p
--- buttons
---- reset
----- button
------ text
---- submit
----- button
------ text
- header
-- closeButton
--- icon
-- consoleButton
--- button
---- text

Components

Some repeating and nested parts were moved to standalone components/parts - Section Description, URI Parameters, Code Examples. In order to style these, you need to update all of its occurrences.

Section Description


p
- strong
- em
- $hover
- a
-- $hover
h1
- $hover
h2
- $hover
h3
- $hover
h4
- $hover
h5
- $hover
h6
- $hover
a
- $hover
- $link
- $visited
- $active
strong
- $hover
em
- $hover
hr
- $hover
img
- $hover
blockquote
- $hover
code
pre
- $hover
- code
-- $hover
ul
- $hover
- li
-- $hover
-- strong
-- em
-- a
--- $hover
table
- $hover
- thead
-- $hover
- tbody
-- $hover
- tfoot
-- $hover
- tr
-- $hover
-- td
--- $hover
-- th
--- $hover
del
ins
abbr
mark
sup
sub
kbd

URI Parameters


parameters
- title
- list
-- parameter
--- $required
--- $optional
--- column
---- icon
---- tooltip
--- key
--- type
--- description
---- Section Description ↝
--- example
---- code
--- default
---- code
--- values
---- invitation
----- icon
---- container
----- text
----- list
------ value
------- text
------- delimiter

Code examples


codeExample
- lineNumber
- line
-- comment
-- prolog
-- doctype
-- cdata
-- punctuation
-- namespace
-- property
-- tag
-- boolean
-- number
-- selector
-- attrName
-- string
-- operator
-- entity
-- url
-- keyword
-- regex
-- important

CSS properties

Properties List of allowed CSS properties.

Embed property CSS Property
background background
backgroundClip background-clip
backgroundColor background-color
backgroundImage background-image
backgroundOrigin background-origin
backgroundPosition background-position
backgroundRepeat background-repeat
backgroundSize background-size
border border
borderBottom border-bottom
borderLeft border-left
borderRadius border-radius
borderRight border-right
borderTop border-top
color color
display display
font font
fontFamily font-family
fontSize font-size
fontStyle font-style
fontVariant font-variant
fontWeight font-weight
margin margin
marginBottom margin-bottom
marginLeft margin-left
marginRight margin-right
marginTop margin-top
padding padding
paddingBottom padding-bottom
paddingLeft padding-left
paddingRight padding-right
paddingTop padding-top
textDecoration text-decoration
textDecorationColor text-decoration-color
textDecorationLine text-decoration-line
textDecorationStyle text-decoration-style
textShadow text-shadow
visibility visibility

We translate these properties and apply them to the Embed docs before rendering.