Speca.io Features Showcase

Introduction
Welcome to Feature Showcase API page!
Simple operation example
Get current user info
GET /me

Operation returns authenticated user details. DIFF DEMO

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
401 Unauthorized
Body
Object
message
string

Detailed response message

Example:
Request requires authentication
OK
Error
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
}
GET https://speca.io/api/me HTTP/1.1 

HTTP/1.1 401 Unauthorized 

Content-Type: application/json

{
    "message": "Request requires authentication"
}
Mock API Server
Mock API Server

API Clients may start calling operation as soon as it’s defined on Speca. Our mock server will match the request by HTTP method and url. It will respond with a randomly generated response that will be 100% valid against response schema (if defined).

Speca provides a single endpoint for all hosted APIs - https://mock.speca.io. You are required to provide particular API details and credentials in HTTP headers:

  • Speca-Owner and Speca-Name you can grab values from the URL for your API project - https://speca.io/[OWNER]/[NAME]
  • Basic Authentication header
  • You also may override matched operation by passing its id in Speca-Operation-Id header
  • You also may specify desired response in case multiple responses are defined for the operation by passing its name in Speca-Response-Name or status in Speca-Response-Status headers.

TryIt Console:

To try Mock API Server right in the editor or from documentation page, just open TryIt Console for any operation and select mock base url at the header section:

Example
# successful response
curl -u SPECA_USERNAME 'https://mock.speca.io/me' -H 'Speca-Owner: speca' -H 'Speca-Name: speca-io-features-showcase'

# error response
curl -u SPECA_USERNAME 'https://mock.speca.io/me' -H 'Speca-Owner: speca' -H 'Speca-Name: speca-io-features-showcase' -H 'Speca-Response-Status: 401'

# disable operation matching, by passing Speca-Operation-Id
curl -u SPECA_USERNAME 'https://mock.speca.io/me' -H 'Speca-Operation-Id: search-for-something-else' -H 'Speca-Owner: speca' -H 'Speca-Name: speca-io-features-showcase'
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. Trait Definition
  • The last thing would be adding Paginated trait to operations that require it:
403 Insufficient permissions
Demo Operations
Search for items
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 
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
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

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