Speca Features Showcase

Yes!

As you can see this version is different !!!

Welcome to Speca.io Feature Showcase API page!

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

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
}

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:

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:
- Search for items
- Search for items (clone)

GET /specs

Request parameters

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

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

GET /specs

Request parameters

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

Responses

200 OK

Body

Array of Item

403 Insufficient permissions

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
}

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

Methods: Search for items Search for items (clone)

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"
}

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.

Advertisement :)

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

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

Lorem ipsum dolor sit amet
Consectetur adipiscing elit
Integer molestie lorem at massa
You can use sequential numbers…
…or keep all the numbers as 1.

Start numbering with offset:

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

Links

link text

link with title

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

Images

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>>;
}