Speca Public API
master
by speca

Speca Public API

Versions
Create version
PUT /specs/{owner}/{urlName}/versions
Update version
POST /specs/{owner}/{urlName}/versions/{version}
List versions
GET /specs/{owner}/{urlName}/versions
Delete version
DELETE /specs/{owner}/{urlName}/versions/{version}
Create version
PUT /specs/{owner}/{urlName}/versions

Path variables

owner
string required

Owner account url name

Example:
my-org
urlName
string required

API url name

Example:
my-rest-api

Request body

Object
name
string required

Version name

Example:
v1.2-draft
from
string required

Name of parent version

Example:
v1.0
desc
string

Version description

Example:
some description
readOnly
boolean

whether this API version can be modified or not

Example:
false
status
VersionStatusEnum

version status

Example:
published

Responses

200 OK
Body
VersionsResponse
Example
curl -X PUT "https://speca.io/api/specs/my-org/my-rest-api/versions"  \
 -H "Content-Type: application/json"  \
 -d '{
    "name": "v1.2-draft",
    "from": "v1.0",
    "desc": "some description",
    "readOnly": "false",
    "status": "published"
}' 

HTTP/1.1 200 OK  
 
Content-Type: application/json 

{
    "counter": 1,
    "default_": 0,
    "versions": [
        {
            "id": 1,
            "from": 0,
            "createdAt": 1543980746920,
            "name": "master",
            "status": "published"
        }
    ]
}
show more
Update version
POST /specs/{owner}/{urlName}/versions/{version}

Path variables

owner
string required

Owner account url name

Example:
my-org
urlName
string required

API url name

Example:
my-rest-api
version
string required

updated version name

Request body

Object
name
string required

new version name

desc
string

version description

readOnly
boolean

whether this API version can be modified or not

status
VersionStatusEnum

version status

Responses

200 OK
Body
VersionsResponse
List versions
GET /specs/{owner}/{urlName}/versions

Path variables

owner
string required

Owner account url name

Example:
my-org
urlName
string required

API url name

Example:
my-rest-api

Responses

200 OK
Body
VersionsResponse
Example
GET https://speca.io/api/specs/my-org/my-rest-api/versions HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "counter": 1,
    "default_": 0,
    "versions": [
        {
            "id": 0,
            "from": 0,
            "createdAt": 1543980746920,
            "name": "master",
            "status": "published"
        },
        {
            "id": 1,
            "from": 0,
            "createdAt": 1550633714908,
            "name": "draft",
            "status": "unpublished"
        }
    ]
}
show more
Delete version
DELETE /specs/{owner}/{urlName}/versions/{version}

Path variables

owner
string required

Owner account url name

Example:
my-org
urlName
string required

API url name

Example:
my-rest-api
version
string required

version name

Responses

202 Accepted
Export
Export HTML bundle
GET /specs/{owner}/{urlName}/bundle
Export API description in OAS3 format
GET /specs/{owner}/{urlName}/oas3
Export API description in Swagger 2.0 format
GET /specs/{owner}/{urlName}/swagger
Export as Postman collection
GET /specs/{owner}/{urlName}/postman
Export HTML bundle
GET /specs/{owner}/{urlName}/bundle

Export API documentation in html format, so it can be hosted by any web server.

Path variables

owner
string required

Owner account url name

Example:
my-org
urlName
string required

API url name

Example:
my-rest-api

Responses

200 OK

Response is zip archive includes published versions of API in html format along with all required assets - js and css files.

application/zip
Export API description in OAS3 format
GET /specs/{owner}/{urlName}/oas3

Path variables

owner
string required

Owner account url name

Example:
my-org
urlName
string required

API url name

Example:
my-rest-api

Request parameters

specVersion
string optional
Example:
0.2
specaExt
boolean optional
Example:
true

Responses

200 OK
Body
Swagger 3.0
Example
GET https://speca.io/api/specs/my-org/my-rest-api/oas3?specVersion=0.2 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "openapi": "3.0.0",
    "info": {
        "title": "Speca Public API",
        "version": ""
    },
    "servers": [
        {
            "url": "https://speca.io/api"
        }
    ],
    "paths": {
        "/specs/{owner}/{urlName}/oas3": {
            "get": {
                "summary": "Export API description in OAS3 format",
                "operationId": "export-api-description-in-oas3-format",
                "parameters": [
                    {
                        "name": "owner",
                        "in": "path",
                        "description": "Owner account url name",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "my-org"
                        }
                    },
                    {
                        "name": "urlName",
                        "in": "path",
                        "description": "API url name",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "my-rest-api"
                        }
                    },
                    {
                        "name": "specVersion",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "example": "0.2"
                        }
                    },
                    {
                        "name": "specaExt",
                        "in": "query",
                        "schema": {
                            "type": "boolean",
                            "example": true
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "Swagger 3.0"
                                }
                            }
                        }
                    }
                }
            }
        },
    ....
}
show more
Export API description in Swagger 2.0 format
GET /specs/{owner}/{urlName}/swagger

Path variables

owner
string required

Owner account url name

Example:
my-org
urlName
string required

API url name

Example:
my-rest-api

Request parameters

specVersion
string optional
Example:
0.2
specaExt
boolean optional

Responses

200 OK
Body
Swagger 2.0
Example
GET https://speca.io/api/specs/my-org/my-rest-api/swagger HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "swagger": "2.0",
    "info": {
        "title": "Speca Public API",
        "version": ""
    },
    "host": "speca.io",
    "basePath": "/api",
    "schemes": [
        "https"
    ],
    "paths": {
        "/specs/{owner}/{urlName}/oas3": {
            "get": {
                "summary": "Export API description in OAS3 format",
                "operationId": "export-api-description-in-oas3-format",
                "parameters": [
                    {
                        "name": "owner",
                        "in": "path",
                        "description": "Owner account url name",
                        "required": true,
                        "type": "string",
                        "example": "my-org"
                    },
                    {
                        "name": "urlName",
                        "in": "path",
                        "description": "API url name",
                        "required": true,
                        "type": "string",
                        "example": "my-rest-api"
                    },
                    {
                        "name": "specVersion",
                        "in": "query",
                        "type": "string",
                        "example": "0.2"
                    },
                    {
                        "name": "specaExt",
                        "in": "query",
                        "type": "boolean",
                        "example": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/Swagger 3.0"
                        }
                    }
                }
            }
        },
    ...    
}
show more
Export as Postman collection
GET /specs/{owner}/{urlName}/postman

Path variables

owner
string required

Owner account url name

Example:
my-org
urlName
string required

API url name

Example:
my-rest-api

Responses

200 OK
Body
Object
id
string
Example:
a6a47569-0e7a-492d-9269-2641daaa9579
name
string
Example:
Speca Public API
timestamp
integer
Example:
1550633310503
order
Array
Example: 
["eaf11938-52e2-4f7c-88b2-827d166823a9","72d82249-67c9-4aef-9a1e-f3b2f0b469a2","746469b7-4002-4e75-95a1-bfd144052897"]
string
Example:
eaf11938-52e2-4f7c-88b2-827d166823a9
folders
Array
Object
id
string
Example:
eaf11938-52e2-4f7c-88b2-827d166823a9
name
string
Example:
Export
order
Array
Example: 
["635624b9-d5d3-4b71-bec9-ef9f37b79e69","61e93b8d-41d4-40e9-96ce-3633d72b5fe2","ef8404f6-b550-4562-9b0c-9e8d040d341a"]
string
Example:
635624b9-d5d3-4b71-bec9-ef9f37b79e69
collection_name
string
Example:
Speca Public API
collection_id
string
Example:
a6a47569-0e7a-492d-9269-2641daaa9579
requests
Array
Object
id
string
Example:
635624b9-d5d3-4b71-bec9-ef9f37b79e69
headers
string
Example:
Accept: application/json Content-Type: application/json
url
string
Example:
https://speca.io/api/specs/:owner/:urlName/postman
method
string
Example:
GET
pathVariables
Object
owner
string
Example:
my-org
urlName
string
Example:
my-rest-api
data
Array of unknown
dataMode
string
Example:
params
name
string
Example:
Export as Postman collection
time
integer
Example:
1550633310504
version
integer
Example:
2
responses
Array
Object
id
string
Example:
1d18189b-87e2-4415-b483-b13f20b956f4
name
string
Example:
Example Response
responseCode
Object
code
integer
Example:
200
name
string
Example:
OK
time
integer
Example:
109
headers
Array of unknown
language
string
Example:
javascript
previewType
string
Example:
html
rawDataType
string
Example:
text
collectionRequestId
string
Example:
635624b9-d5d3-4b71-bec9-ef9f37b79e69
collectionId
string
Example:
a6a47569-0e7a-492d-9269-2641daaa9579
synced
boolean
show more
Example
GET https://speca.io/api/specs/my-org/my-rest-api/postman HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "a6a47569-0e7a-492d-9269-2641daaa9579",
    "name": "Speca Public API",
    "timestamp": 1550633310503,
    "order": [
        "eaf11938-52e2-4f7c-88b2-827d166823a9",
        "72d82249-67c9-4aef-9a1e-f3b2f0b469a2",
        "746469b7-4002-4e75-95a1-bfd144052897"
    ],
    "folders": [
        {
            "id": "eaf11938-52e2-4f7c-88b2-827d166823a9",
            "name": "Export",
            "order": [
                "635624b9-d5d3-4b71-bec9-ef9f37b79e69",
                "61e93b8d-41d4-40e9-96ce-3633d72b5fe2",
                "ef8404f6-b550-4562-9b0c-9e8d040d341a"
            ],
            "collection_name": "Speca Public API",
            "collection_id": "a6a47569-0e7a-492d-9269-2641daaa9579"
        },
        {
            "id": "72d82249-67c9-4aef-9a1e-f3b2f0b469a2",
            "name": "Preview Updates",
            "order": [
                "3bd7c5cd-a31e-4ec2-a8b6-82b6fbe5331e",
                "a95f7048-e4f6-468b-9373-c866b963abe5"
            ],
            "collection_name": "Speca Public API",
            "collection_id": "a6a47569-0e7a-492d-9269-2641daaa9579"
        },
        {
            "id": "746469b7-4002-4e75-95a1-bfd144052897",
            "name": "Update",
            "order": [
                "95cd63ea-5b2f-4732-ba6d-048b6abbbf6f",
                "195c422b-9365-410c-91e1-d301b299f123"
            ],
            "collection_name": "Speca Public API",
            "collection_id": "a6a47569-0e7a-492d-9269-2641daaa9579"
        }
    ],
    "requests": [
        {
            "id": "635624b9-d5d3-4b71-bec9-ef9f37b79e69",
            "headers": "Accept: application/json\nContent-Type: application/json\n",
            "url": "https://speca.io/api/specs/:owner/:urlName/postman",
            "method": "GET",
            "pathVariables": {
                "owner": "my-org",
                "urlName": "my-rest-api"
            },
            "data": [],
            "dataMode": "params",
            "name": "Export as Postman collection",
            "time": 1550633310504,
            "version": 2,
            "responses": [
                {
                    "id": "1d18189b-87e2-4415-b483-b13f20b956f4",
                    "name": "Example Response",
                    "responseCode": {
                        "code": 200,
                        "name": "OK"
                    },
                    "time": 109,
                    "headers": [],
                    "language": "javascript",
                    "previewType": "html",
                    "rawDataType": "text",
                    "collectionRequestId": "635624b9-d5d3-4b71-bec9-ef9f37b79e69"
                }
            ],
            "collectionId": "a6a47569-0e7a-492d-9269-2641daaa9579",
            "synced": false
        },
        
        {
            "id": "a95f7048-e4f6-468b-9373-c866b963abe5",
            "headers": "Accept: application/json\nContent-Type: application/json\nSpeca-Version: \n",
            "url": "https://speca.io/api/specs/:owner/:name/mergeSwaggerPreview?mode=merge",
            "method": "POST",
            "pathVariables": {
                "owner": "",
                "name": ""
            },
            "dataMode": "raw",
            "name": "Show diff between spec and Swagger 2.0 definition",
            "description": "This operation let you preview updates that will be result of update API with provided spec in Swagger 2.0 format.\nIn other words operation produces a diff between API definition in Speca and provided document.",
            "time": 1550633310504,
            "version": 2,
            "responses": [
                {
                    "id": "b4e8a989-79de-4a09-883d-33da891bcbf6",
                    "name": "Example Response",
                    "responseCode": {
                        "code": 200,
                        "name": "OK"
                    },
                    "time": 109,
                    "headers": [],
                    "language": "javascript",
                    "previewType": "html",
                    "rawDataType": "text",
                    "collectionRequestId": "a95f7048-e4f6-468b-9373-c866b963abe5"
                }
            ],
            "collectionId": "a6a47569-0e7a-492d-9269-2641daaa9579",
            "synced": false
        },
        {
            "id": "95cd63ea-5b2f-4732-ba6d-048b6abbbf6f",
            "headers": "Accept: application/json\nContent-Type: application/json\nSpeca-Version: \n",
            "url": "https://speca.io/api/specs/:owner/:urlName/mergeSpec?mode=merge",
            "method": "POST",
            "pathVariables": {
                "owner": "",
                "urlName": ""
            },
            "dataMode": "raw",
            "name": "Update API with a Spec Definition in internal format",
            "time": 1550633310504,
            "version": 2,
            "responses": [
                {
                    "id": "6e799501-7969-41e8-9627-93f78f28aba6",
                    "name": "Example Response",
                    "responseCode": {
                        "code": 200,
                        "name": "OK"
                    },
                    "time": 109,
                    "headers": [],
                    "language": "javascript",
                    "previewType": "html",
                    "rawDataType": "text",
                    "collectionRequestId": "95cd63ea-5b2f-4732-ba6d-048b6abbbf6f"
                }
            ],
            "collectionId": "a6a47569-0e7a-492d-9269-2641daaa9579",
            "synced": false
        },
       ...
    ]
}
show more
Import
Preview Updates
Show diff between spec and uploaded API definition
POST /specs/{owner}/{name}/uploadUpdatePreview
Show diff between spec and Swagger 2.0 definition
POST /specs/{owner}/{name}/mergeSwaggerPreview
Show diff between spec and uploaded API definition
POST /specs/{owner}/{name}/uploadUpdatePreview

This operation let you preview updates that will be result of update API with provided spec in either Swagger 2.0 or Open API format. In other words operation produces a diff between API definition in Speca and provided document.

Path variables

owner
string required
name
string required

Request parameters

mode
string required

Merge definitions mode.

Enumeration:
merge

Preserve groups hierarchy, document items, traits and shared items. Merge operations and schemas, by default description and examples are not updated.

replace

Preserve group hierarchy and document items, all other definitions get deleted. New items are created from the submitted document.

add

Add new items, existent definitions stay untouched

Example:
merge
updateDesc
boolean optional

If true, descriptions will be updated with the ones coming in uploaded document.

Default:
false
updateExamples
boolean optional

If true, examples will be updated with the ones coming in uploaded document.

Default:
false
removeOrphans
boolean optional

Remove items that are no longer referred by any other objects

Request headers

Speca-Version
string optional

This header can be passed in every API endpoint that reads or updates API spec, if you omit the header that means you deal with the default version.

Request body

multipart/form-data

OpenAPI document, both Swagger 2.0 and OpenAPI 3 are accepted

Responses

200 OK
Body
PreviewResponse
Example 1
POST https://speca.io/api/specs/speca/petstore-api/uploadUpdatePreview?mode=merge HTTP/1.1 

Content-Type: multipart/form-data

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "data": {
        ....
    },
    "created": [
        {
            "id": "updatePet",
            "name": "Update an existing pet",
            "type": "method"
        },
        {
            "id": "placeOrder",
            "name": "Place an order for a pet",
            "type": "method"
        }
        ...
    ],
    "updated": [
        {
            "id": "Pet",
            "name": "pet",
            "type": "schema"
        }
        ...
    ],
    "deleted": []
}
show more
Show diff between spec and Swagger 2.0 definition
POST /specs/{owner}/{name}/mergeSwaggerPreview

This operation let you preview updates that will be result of update API with provided spec in Swagger 2.0 format. In other words operation produces a diff between API definition in Speca and provided document.

Path variables

owner
string required
name
string required

Request parameters

mode
string required

Merge definitions mode.

Enumeration:
merge

Preserve groups hierarchy, document items, traits and shared items. Merge operations and schemas, by default description and examples are not updated.

replace

Preserve group hierarchy and document items, all other definitions get deleted. New items are created from the submitted document.

add

Add new items, existent definitions stay untouched

Example:
merge
updateDesc
boolean optional

If true, descriptions will be updated with the ones coming in uploaded document.

Default:
false
updateExamples
boolean optional

If true, examples will be updated with the ones coming in uploaded document.

Default:
false
removeOrphans
boolean optional

Remove items that are no longer referred by any other objects

Request headers

Speca-Version
string optional

This header can be passed in every API endpoint that reads or updates API spec, if you omit the header that means you deal with the default version.

Request body

application/json
Swagger 2.0

Responses

200 OK
Body
PreviewResponse
Example 1
POST https://speca.io/api/specs/speca/petstore-api/uploadUpdatePreview?mode=merge HTTP/1.1 

Content-Type: application/json

{
    "swagger": "2.0",
    "paths": {
        ...
    }
    "definitions": {
        ...
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "data": {
        ....
    },
    "created": [
        {
            "id": "updatePet",
            "name": "Update an existing pet",
            "type": "method"
        },
        {
            "id": "placeOrder",
            "name": "Place an order for a pet",
            "type": "method"
        }
        ...
    ],
    "updated": [
        {
            "id": "Pet",
            "name": "pet",
            "type": "schema"
        }
        ...
    ],
    "deleted": []
}
show more
Update
Update API with a Spec Definition in internal format
POST /specs/{owner}/{urlName}/mergeSpec

Path variables

owner
string required
urlName
string required

Request parameters

group
string optional

Id of the group new items will be placed in.

Example:
last-import
mode
string required

Merge definitions mode.

Enumeration:
merge

Preserve groups hierarchy, document items, traits and shared items. Merge operations and schemas, by default description and examples are not updated.

replace

Preserve group hierarchy and document items, all other definitions get deleted. New items are created from the submitted document.

add

Add new items, existent definitions stay untouched

Example:
merge
updateDesc
boolean optional

If true, descriptions will be updated with the ones coming in uploaded document.

Default:
false
updateExamples
boolean optional

If true, examples will be updated with the ones coming in uploaded document.

Default:
false
removeOrphans
boolean optional

Remove items that are no longer referred by any other objects

Request headers

Speca-Version
string optional

This header can be passed in every API endpoint that reads or updates API spec, if you omit the header that means you deal with the default version.

Request body

API definition in Speca internal format (result of Preview update operation)

SpecaObject

Responses

200 OK
Update API with Swagger 2.0 Document
POST /specs/{owner}/{urlName}/mergeSwagger

Path variables

owner
string required
urlName
string required

Request parameters

group
string optional

Id of the group new items will be placed in. If empty, all the new items will become children of the root group.

Default:
""
Example:
last-import
mode
string required

Merge definitions mode.

Enumeration:
merge

Preserve groups hierarchy, document items, traits and shared items. Merge operations and schemas, by default description and examples are not updated.

replace

Preserve group hierarchy and document items, all other definitions get deleted. New items are created from the submitted document.

add

Add new items, existent definitions stay untouched

Example:
merge
updateDesc
boolean optional

If true, descriptions will be updated with the ones coming in uploaded document.

Default:
false
updateExamples
boolean optional

If true, examples will be updated with the ones coming in uploaded document.

Default:
false
removeOrphans
boolean optional

Remove items that are no longer referred by any other objects

Request headers

Speca-Version
string optional

This header can be passed in every API endpoint that reads or updates API spec, if you omit the header that means you deal with the default version.

Request body

Swagger 2.0

Responses

200 OK
Type Definitions
speca
VersionsResponse
Object
counter
integer

@deperecated to be removed

Example:
1
default_
integer

default version id

versions
Array
Object
id
integer
Example:
1
from
integer

parent version id

Example:
0
createdAt
integer
Example:
1543980746920
name
string
Example:
master
status
VersionStatusEnum
VersionStatusEnum
string
Enumeration:
published
archived
draft
SpecaObject
Object
info
string
base_url
string
base_url_vars
Array of Param
content_types
Array of string
tags
Array of string
groups
Array of Group
docs
Array of Doc
methods
Array of Method
schemas
Array of Schema
params
Array of Param
reqHeaders
Array of Param
resHeaders
Array of Param
responses
Array of Param
auth_definitions
Array of AuthDefinition
show more
Group
Object
Doc
Object
Schema
Object
Method
Object
Param
Object
AuthDefinition
Object
PreviewResponse
Object
Example: 
{
    "data": {},
    "created": [
        {
            "id": "pet",
            "name": "Pet",
            "type": "method"
        }
    ],
    "updated": [
        {
            "id": "user",
            "name": "User",
            "type": "schema"
        }
    ],
    "deleted": [
        {
            "id": "deprecated-param",
            "name": "Deprecated Param",
            "type": "param"
        }
    ]
}
data
SpecaObject

Result API definition in internal Speca format

created
Array of MergeResultItem

List of items that doesn’t exist and will be created

updated
Array of MergeResultItem

List of existing items that will be updated

deleted
Array of MergeResultItem

List of items that will be deleted

MergeResultItem
Object
id
string

item unique id

name
string

item name

type
string

item type

Enumeration:
method
schema
response
param
header
Swagger 2.0
Swagger 2.0 Spec

Please checkout original specification here

Object
additional properties
string
Swagger 3.0
OAS Spec

See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md

Object
additional properties
string
Speca-Version
string optional

This header can be passed in every API endpoint that reads or updates API spec, if you omit the header that means you deal with the default version.