Speca.io Features Showcase

Introduction

Welcome to Speca.io Feature Showcase API page!

Let’s start with documenting simplest operation you can imagine…

Simple operation example
Get current user info
GET /me

You can try to call /me if you are authenticated.

Responses

200 OK
Body
Object
username
string
Example:
speca
displayName
string
Example:
speca
email
string
Example:
speca@speca.io
imageUrl
string
Example:
https://secure.gravatar.com/avatar/2222?d=mm&s=40
social
boolean
plan
string
Example:
O1
active
boolean
Example:
true
Example
GET https://speca.io/api/me HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "username": "speca",
    "displayName": "speca",
    "email": "speca@speca.io",
    "imageUrl": "https://secure.gravatar.com/avatar/2222?d=mm&s=40",
    "social": true,
    "plan": "O1",
    "active": true
}
Prevent Duplication & Increase Maintainability
Pagination

Speca.io provides you advanced features to completely avoid duplication in your content. Let’s consider Pagination

Sometimes your API endpoint might return a lot of results. In this case it make sense to paginate results to make them easier > to process by server, transfer and handle on the client side.

It’s pretty common that API contains multiple endpoinds that return paginated response, so to avoid duplicatios and make documentation easily maintainable we …

  • Create two common parameters - page and size, which would look lekie this:
page_size
number required

Number of items to include in the result

Min: 0
Max: 1,000
Default:
100
page
number required

offset result items

Default:
0
Pagination - Trait
  • Create a Trait (i.e. partial, abstract operation, or operation template that defines common parts and behaviors for multiple operations). We are going to name it Paginated, and we are going to make references to both common parameters we defined earlier.
  • The last thing would be adding Paginated trait to operations that require it:
403 Insufficient permissions
Demo Operations
Search for items
GET /specs

Responses

200 OK
Body
Array of Item
403 Insufficient permissions
OK
Forbidden
GET /items/search?page_size=1&page=1 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

[
    {
        "users": [
            {
                "id": 1,
                "name": "Adam Carter",
                "work": "Unilogic",
                "email": "adam.carter@unilogic.com",
                "dob": "1978",
                "address": "83 Warner Street",
                "city": "Boston",
                "optedin": true
            }
        ],
        "images": [
            "img0.png"
        ],
        "coordinates": {
            "x": 35.12,
            "y": -21.49
        },
        "price": 1,
        "type": "Model S"
    }
]
GET /items/search?page_size=100 HTTP/1.1 

HTTP/1.1 403 Forbidden 
Search for items (clone)
GET /specs

Responses

200 OK
Body
Array of Item
403 Insufficient permissions
Type Definitions
User

Have you ever seen an API that has no Users?

Also you can see that this Schema is referenced by Item

Object
id
integer
name
string
Max length: 100
Example:
Adam Carter
work
string
Example:
Unilogic
email
string email
Example:
adam.carter@unilogic.com
dob
string
Example:
1978
address
string
Example:
83 Warner Street
city
string
Example:
Boston
optedin
boolean
Example:
true
Types: Item
Example 1
{
    "id": 1,
    "name": "Adam Carter",
    "work": "Unilogic",
    "email": "adam.carter@unilogic.com",
    "dob": "1978",
    "address": "83 Warner Street",
    "city": "Boston",
    "optedin": true
}
Item

Whatever Item our Showcase API deal with, but it demostrates:

  • Reference to another Schema Definition;
  • Nested and Array Schema Definition;
  • Enumerated property example;
  • Various formats in properties;
  • …and couple examples in the right sidebar ----------------------------------------->
Object
users
Array of User
images
Array
Example:
["img0.png","img1.png","img2.png"]
string
Max length: 256
Example:
img0.png
coordinates
Object
Example:
{
    "x": 35.12,
    "y": -21.49
}
x
number float
Example:
35.12
y
number double
Example:
-21.49
price
number Money

Item price

type
string nullable
Enumeration:
Model X

Item type Model X

Model S

Item type Model S

Default:
Model S
Example 1
Example 2

Item with No Users

{
    "users": [], //Json with comments, Huh?
    "images": [
        "img0.png"
    ],
    "coordinates": {
        "x": 35.12,
        "y": -21.49
    },
    "price": "$59,395"
}

Uuh, one user now!

{
    "users": [
        {
            "id": 1,
            "name": "Adam Carter",
            "work": "Unilogic",
            "email": "adam.carter@unilogic.com",
            "dob": "1978",
            "address": "83 Warner Street",
            "city": "Boston",
            "optedin": true
        }
    ],
    "images": [
        "img0.png"
    ],
    "coordinates": {
        "x": 35.12,
        "y": -21.49
    },
    "price": "$59,395"
}
Other features
Deep nesting
nested
nested nested
nested nested nested
super nested!
What is Lorem Ipsum?

Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry’s standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.

CommonMark Syntax

Advertisement :)

  • pica - high quality and fast image resize in browser.
  • babelfish - developer friendly i18n with plurals support and easy syntax.

You will like those projects!


h1 Heading 8-)

h2 Heading

h3 Heading

h4 Heading

h5 Heading
h6 Heading

Horizontal Rules




Typographic replacements

Enable typographer option to see result.

© © ® ® ™ ™ § § ±

test… test… test… test?.. test!..

!!! ??? , – —

“Smartypants, double quotes” and ‘single quotes’

Emphasis

This is bold text

This is bold text

This is italic text

This is italic text

Strikethrough

Blockquotes

Blockquotes can also be nested…

…by using additional greater-than signs right next to each other…

…or with spaces between arrows.

Lists

Unordered

  • Create a list by starting a line with +, -, or *
  • Sub-lists are made by indenting 2 spaces:
    • Marker character change forces new list start:
      • Ac tristique libero volutpat at
      • Facilisis in pretium nisl aliquet
      • Nulla volutpat aliquam velit
  • Very easy!

Ordered

  1. Lorem ipsum dolor sit amet

  2. Consectetur adipiscing elit

  3. Integer molestie lorem at massa

  4. You can use sequential numbers…

  5. …or keep all the numbers as 1.

Start numbering with offset:

  1. foo
  2. bar

Code

Inline code

Indented code

// Some comments
line 1 of code
line 2 of code
line 3 of code

Block code “fences”

Sample text here...

Syntax highlighting

var foo = function (bar) {
  return bar++;
};

console.log(foo(5));

Tables

Option Description
data path to data files to supply the data that will be passed into templates.
engine engine to be used for processing templates. Handlebars is the default.
ext extension to be used for dest files.

Right aligned columns

Option Description
data path to data files to supply the data that will be passed into templates.
engine engine to be used for processing templates. Handlebars is the default.
ext extension to be used for dest files.

link text

link with title

Autoconverted link https://github.com/nodeca/pica (enable linkify to see)

Images

Minion

New Feature!
TypeScript

Code examples in documentation sections!!!

{
    "simle": "json",
    "example": true
}

TypeScript is now supported!

interface AsyncIterator<T> {
  next(value?: any): Promise<IteratorResult<T>>;
  return?(value?: any): Promise<IteratorResult<T>>;
  throw?(e?: any): Promise<IteratorResult<T>>;
}