zdne

# Data Document

This document contains a description of a data.

# Data Structures

## Some Data (object)

- name: Z (string) - Good old name.

zdne

Working with multiple blueprint files

This document describes 4 different solutions to work APIs that consist of multiple blueprint files. Every of this solution work with all Apiary.io features but editing. To edit a blueprint you have to do it outside of Apiary as Apiary editor does not support working with multiple files. In other words if you are using one of the solutions below avoid editing the blueprint in Apiary.

1. Hercule

Hercule is a CLI tool written in Node.js – available as an NPM package. It uses markdown referencing and linking syntax to transclude other files into a blueprint file. This solution is universal and would work with any Markdown files not just API Blueprint.

The major benefit – unlike any other solutions here – is also that the references are rendered as HTML links in any Markdown editor so the result is HTML that can be browsed!

zdne

#!/bin/bash

echo -n "GitHub User: "
read USER

echo -n "GitHub Password: "
read -s PASS

echo ""
echo -n "GitHub Repo (e.g. foo/bar): "

zdne

$KEY: $VALUE

$API_NAME

$DESCRIPTION

group $GROUP_NAME

$DESCRIPTION

$RESOURCE_NAME [$URI_TEMPLATE]

$DESCRIPTION

zdne

FORMAT: 1A

# Gist Fox API
Gist Fox API is a **pastes service** similar to [GitHub's Gist](http://gist.github.com).

## Authentication
*Gist Fox API* uses OAuth Authorization. First you create a new (or acquire existing) OAuth token using Basic Authentication. After you have acquired your token you can use it to access other resources within token' scope.

## Media Types
Where applicable this API uses the [HAL+JSON](https://github.com/mikekelly/hal_specification/blob/master/hal_specification.md) media-type to represent resources states and affordances.

zdne

HAL Object

• _links - Links (to URIs)

  • {relation name}

    A resource may have multiple links that share the same link relation. For link relations that may have multiple links, we use an array of links.

    • One of
      • (Relation)
      • (array: Relation)

zdne

#include <string>
#include <vector>
#include <regex>

enum MarkdownNodeType {
    RootMarkdownNodeType = 0,
    HeaderMarkdownNodeType,
    ListItemMarkdownNodeType,
    ParagraphMarkdownNodeType,
    UndefinedMarkdownNodeType = -1

zdne

express = require 'express'
app = express()

PORT = 1234

app.get '/machines', (req, res) ->
  res.setHeader 'Content-Type', 'application/json'
  machine =
    type: 'bulldozer'
    name: 'willy'

zdne

Modeling API

Question: Affordances or web link relations for modeling your API?

I have been pondering this question a lot lately. Given a resource and its attributes (semantic descriptors), would you model the API using the link / relations or resource affordances? May one relation as defined by RFC5988 Web Linking imply multiple affordances? For example does the edit relation represents three affordances (retrieve, update, and delete)?

Is (should?) the perspective affordances vs. relations differ based on the point of view (API design, client, server).

Most of the hypermedia media types such as HAL, Collection+JSON and JSON API are built around link relations. Seems that on

zdne

My API

Lorem Ipsum

Group My Stuff

My Message [/message]

• Response 200 (text/plain)

    Hello World!