Please remember that our API is in beta. Although it is versioned, things can change, for example in the structure of documents. We will try to update this documentation as soon as things change. If you have any question, please send an email to firstname.lastname@example.org so one of our developers can help you out.
We changed domains: please change any mentions of silkapp.com in the code examples to silk.co.
If you understand how the API works, here is a complete overview of all API paths.
Silk has a REST based API for reading and writing. This is the basic documentation (for version 1.4.0 of the API) with the most important concepts and logic. Silk itself runs on its own API. So everything you can do on Silk, you can do with the API.
These entities within Silk are important:
- Site - a collection of pages, such as world.silk.co
- Page - a document, for example world.silk.co/page/Monaco.
- User - a user with permissions on one or more sites.
- Taglist - a list with the semantic structure of the site.
- Query - a way to search, filter and combine tags within a site.
To minimize breaking existing projects, Silk uses a layered API with a custom versioning scheme. Read more about it here.
We explain the API by a few examples in which we show some basic operations. In these examples Curl is used. Curl is a (multi-platform) command line tool for transferring data with URL syntax. It is transparent what request is sent to the API. We will add libraries for multiple languages in the future.
Get a page
Another GET to the API which gives you information about the site (name, description) as well as the access levels for the current user (canRead, canWrite, isAdmin).
Signing in and authentication
To sign in you must POST XML to /user/signin like this
The response (in case of a successful login) is XML with information about the logged-in user. The -i parameter was added because it outputs the header, in this header a cookie is sent: silk_sid, it must be used to authenticate the user in subsequent requests.
Get information about the current user
In the previous step we logged in and got a cookie (silk_sid). We use this cookie in subsequent requests to authenticate. For information about the current user do
The first call gives back information aabout the current user, the second call returns a list of the sites you have access to (read and write).
Create a page
To create a page, we simply post a page (valid! XML) to the API url like this:
There is no difference between creating a new page and updating an existing page. Because Silk holds all the versions of a page, an update to a page can always be reversed.
Get site structure
The semantic structure (information about all the tags) of a site is stored in the taglist.
The taglist contains all information that Silk has about the structure (the tags and categories) of a page.
Do a simple query
We can search through tags and categories within a Silk site. Silk uses a custom query language (explained here) for this. With this query language we can do a query on e.g. world.silk.co (a Silk site about countries). We want to know the countries that have negative population growth: