Silk Import API

Erik Hesselink edited this page Apr 20, 2015 · 2 revisions

Silk Import API

This is a work in progress and subject to change.

This document describes how to create a new silk site, perform an import to it and give another user access to it. We may at a later stage also want to consider the case where a user already has a site which he wants to import to.

During development and testing, replace api.silk.co with api.silk-testing.co.

node.js client

You can install our node.js client

npm install silk-api-client

This gist also contains an example.

Logging in to the Silk API

You will have a Silk account, for instance silk@example.com with the password letmein.

curl https://api.silk.co/v1.16/user/signin/ \
  -X POST \
  -H 'Content-Type:application/json' \
  -d '{"email":"silk@example.com","password":"letmein"}' \
  -i

Response:

HTTP/1.1 200 OK
[...]
Set-Cookie: silk_sid="0g14+kW3hk2zQ7Qj+nlNwA=="; path=/; expires=Sat, 03-May-2014 08:51:06 GMT; domain=api.silk.co
[...]

{"admin":false,"name":"Silk Test","email":"silk@example.com","emailNews":false,"created":"2014-05-01T16:03:05Z","uuid":"aff64629-cee5-46dd-9372-1f856198dc0"}

The silk_sid cookie must be used for authentication in subsequent requests

Checking site availability

curl https://api.silk.co/v1.16/site/available \
  -b 'silk_sid=...' \
  -X POST \
  -H 'Content-Type:text/plain' \
  -d '<NAME>.silk.co'

Response (success):

true

Creating a site

curl https://api.silk.co/v1.16/site/uri/<NAME>.silk.co \
  -b 'silk_sid=...' \
  -X PUT \
  -H 'Content-Type:application/json' \
  -d '{"name":"<NAME>","template":"default"}'

This request gives a HTTP 200 on success.

Creating an import job

curl https://api.silk.co/v1.16/site/uri/<NAME>.silk.co/import/upload-json \
  -b 'silk_sid=...' \
  -X POST \
  -H 'Content-Type:application/json' \
  -d '[{"name":"Sweden", "population":"8000000", "neighbors":["Norway","Finland","Denmark"]}]'

See the format for uploads for the complete JSON format.

You can also use the upload endpoint intsead of upload-json to upload JSON or CSV files. The conent-type must then be application/octet-stream.

Response type: Import

This response contains an importId property that is used to identify subsequent requests.

Updating settings

curl https://api.silk.co/v1.16/site/uri/<NAME>.silk.co/import/id/190cde13-65c1-4d54-ae09-4a31971c8310 \
  -b 'silk_sid=...' \
  -X PUT \
  -H 'Content-Type:application/json' \
  -d mySettings

This request gives the same type of response as the original POST.

Previewing page structure

When importing a CSV you can preview the generated JSON structure, this is also possible for JSON uploads but you will get the same data as you uploaded back (although the number of pages will be limited).

curl https://api.silk.co/v1.16/site/uri/<NAME>.silk.co/import/id/190cde13-65c1-4d54-ae09-4a31971c8310/preview \
  -b 'silk_sid=...' \
  -X POST \
  -i \
  -H 'Content-Type:application/json'

This will return a subset of the pages, in the same format as the accepted JSON upload, some values may have a different format depending on the specified Settings.

Response type: Array<Page>

Starting an import

curl https://api.silk.co/v1.16/site/uri/<NAME>.silk.co/import/id/190cde13-65c1-4d54-ae09-4a31971c8310/start \
  -b 'silk_sid=...' \
  -X POST \
  -H 'Content-Type:application/json'
  -d RunSettings

If you received a warning about already existing page URIs you need to either rename the pages or pass { ignoreExisting : true } to run the import

Checking the status/progress of an import

curl https://api.silk.co/v1.16/site/uri/<NAME>.silk.co/import/id/190cde13-65c1-4d54-ae09-4a31971c8310/progress \
  -b 'silk_sid=...' \
  -X POST \
  -i
  -H 'Content-Type:application/json'

Response type Progress

Aborting an import

  • A job that is new or inProgress can be aborted. Depending on the timing an inProgress import may complete before the abort request is handled.
curl http://api.silk.co/v1.16/site/uri/<NAME>.silk.co/import/id/aa271758-8290-43cc-a790-7244d014e9act \
  -b 'silk_sid=...' \
  -X DELETE \
  -i
  -H 'Content-Type:application/json'

Resetting an import

An import that has progress errored or aborted may be reset to change it's progress to new. It will keep the associated uploaded pages and settings, and can be configured and started as a normal new import.

curl http://api.silk.co/v1.16/site/uri/<NAME>.silk.co/import/id/aa271758-8290-43cc-a790-7244d014e9ac/reset \
  -b 'silk_sid=...' \
  -X POST \
  -i
  -H 'Content-Type:application/json'

One-shot imports

This has not been implemented yet

For an immediate import the upload, configure, and start end points can be combined assuming you are uploading pages in the JSON format.

Inviting a User

curl https://api.silk.co/v1.16/site/uri/<NAME>.silk.co/invite/email/<EMAIL>
  -b 'silk_sid=...' \
  -H 'Content-Type:application/json' \
  -d '{"canRead":true,"canWrite":true,"isAdmin":true}'

After this the user will receive an invitation e-mail to become an admin on the site and can then remove the user that did the import if he wishes.

JSON format

Page

Property Type
uri string
title string
collection string
facts Array<PageFact>
header Array<Component>
leftColumn Array<Component>
mainColumn Array<Component>

Component

type: PageImage|PageParagraph

PageFact

Property Type
tag string
text string
link optional string
index int

PageImage

Property Type
tag string
href string
description optional string
dimensions optional Tuple<int,int>
index int

PageParagraph

Property Type
paragraph string
index int

ColumnValue

type: number|string

Import

Property Type Description
importId string UUID for this import, used to identify requests
site string The uri of the site the import belongs to
user string UUID of the user who created the import
warnings Warnings Warnings generated for the current settings
settings Settings Settings for this import
filetype string "json" or "csv"

Example

{ "importId" : "7fafb525-4dff-4caa-bff6-b8ac0d172850"
, "fileType" : "json"
, "warnings" : Warnings
, "user"     : "e3295813-7c1b-45cf-bfce-6d0316181f0b"
, "site"     : "test.silk.co"
, "settings" : Settings
}

Settings

After uploading a JSON or CSV file the response will contain default settings for the import that can be overwritten.

Property Type Description
collection string The collection to use for all pages
uri ColumnFormat The uri pages will get
title ColumnFormat The HTML title of pages
fields Array<Field> Mappings from columns to components in silk pages

Example

{ "uri"        : {"column":"name"}
, "collection" : "Import"
, "title"      : {"column":"name"}
, "fields"     : []
}

Field

type: Fact|Image|Paragraph

Fact

Property Type Description
type string "fact"
tag string The tag name to put in the fact sheet
text string The textual value of this tag
pageUrl optional ColumnFormat A page name to link the text value to
url optional ColumnFormat A URL to link the text value to

pageUrl and url are mutually exclusive.

Example

{ "type" : "fact", "tag" : "neighbor", "text" : { "column" : "neighbors" }, pageUrl : { "column" : "neighbors" } }

Note that tag and column can have different values.

Image

Property Type Description
type string "image"
tag string Tag the image with this
url ColumnFormat The image src
placement Placement Where to place the image

Example

{ "type"      : "image"
, "tag"       : "flag"
, "url"       : { "column" : "flag" }
, "placement" : "mainColumn"
}

Paragraph

Property Type Description
type string "paragraph"
text ColumnFormat The text content of the paragraph
placement Placement Where to place the paragraph

Example

{ "type"  : "paragraph"
, "text"  : { "column" : "National Anthem" }
}

ColumnFormat

type: ColumnItem|Array<ColumnItem>

The array must be non-empty.

Defines a mapping from columns to textual values, if you have several elements in this array the result will be cross product of values.

Example - Adding textual data to list items

Given the page

{ "name" : "Sweden", "neighbors" : ["Norway","Finland"] }

and the ColumnFormat

[{ text : "The country of " }, { column : "neighbors" }]

The resulting values would be

[ "The country of Norway"
, "The country of Finland"
]

ColumnItem

type: ColumnRef|ConstantText

ConstantText

Property Type Description
text string Constant textual value

ColumnRef

Property Type Description
column string The name of a column
split optional string If specified, splits the values of the specified column using this string

Splitting is mostly for CSVs. If you are uploading a document in the JSON format you can just pass an array instead.

Placement

type: "mainColumn"|"leftColumn"|"header"

Warnings

Property Type Description
existing optional Array<string> Page uris that already exist on this site
pageLimitExceeded optional PageLimitExceeded The site would have too many pages
duplicates optional Map<string,int> Pages with duplicates uris, you can still import with this warning

PageLimitExceeded

Property Type Description
exceededBy int The page limit of this site was exceeded by the specified amount
pageLimit int The page limit of the site

RunSettings

Property Type Description
ignoreExisting bool Whether to override existing pages on the site

Progress

The possible progress responses are:

  • { "new" : {} }: The import has not been started (a request has not been sent to start)
  • { "queued" : {} }: The import is waiting to start
  • { "inProgress" : { "total" : 100, "imported" : 30, "errored" : 0 } }: The import is being performed. The progress updates while the import is running
  • { "calculatingTagList" : {} }: The tag metadata for this import is being calculated.
  • { "completed" : {} }: The import has been successfully performed
  • { "errored" : {} }: There was an error finishing the import, you can restart to reset the status to new
  • { "aborted" : {} }: The import was manually aborted, you can restart to reset the status to new

Upload

type: Array<Row>

Row

type: Map<Cell>

Cell

type: string|number|Array<Cell>

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.