Loading... Loading ...
expand / collapse all

Contents

  1. Introduction
  2. Authentication
  3. Output format
  4. Block ordering
  5. Markdown fields
  6. Activities & paging
  7. Errors
  8. Try the API out
  9. Version history

Introduction

Below you'll find the documentation for the ZEEF API. The ZEEF API is a restful API and is currently in BETA phase. Some API calls and output formats may change between now and when the API is made public. The API is currently only available to users on an invite-only basis. If you would like access to the API, please contact info@zeef.com.

Authentication

The ZEEF API uses a header based stateless token authentication system. To get started with using the ZEEF API, you first will need to create a login token for the API. This can be done from the tokens page of the ZEEF dashboard. On this page, click on generate token and select an expiration date and provide a name for your token. It's best to choose a name that provides a clear description of what the token will be used for. Your tokens must be kept secret and must not be shared with anyone else as doing so will let them gain access to your account. For this reason the API also only supports calls over HTTPS. If you believe your token may have been compromised, it can be revoked from the tokens page of the ZEEF dashboard.

In order to authenticate with the ZEEF API, you need to add an Authorization HTTP header to your request. The value of this header field needs to start with "OmniLogin auth=" followed by your API token. For example, if your token is "XYZ", then you would add the following header to your HTTP requests:

Authorization: OmniLogin auth=XYZ

If you'd like to use cURL to call the ZEEF API, you can add the authorization header using the -H command line flag:

curl -H "Authorization: OmniLogin auth=XYZ" https://zeef.io/api/pages/mine

If authentication was successful, then a header named "ZEEF-username" will be present in the HTTP headers of the response. This header contains the username of the current user as a value. In the case that the authentication failed, this header will not be present.

Output format

The ZEEF API supports both JSON(application/json) and XML(application/xml) for most method calls(see specific method calls for further information), where JSON is the default format. The character encoding used for both formats is UTF-8. There are two ways to select which output format you will receive. The first is to add a HTTP Accept header with the desired mimetype to your request. For example, if you would want the API output to be in XML format, you would add the following header to your request:

Accept: application/xml

It's also possible to indicate the desired output format using the "format" query parameter. The accepted values for this parameter are "json" and "xml". If both the Accept header and the format query parameter are present in a request, then the query parameter will take precedence over the header.

Block ordering

The blocks on a ZEEF page should be laid out in the order they are within the page object, using an overflow based layout, from left to right. For example, if there are exactly X columns, then the first X blocks should be on the first row, the next X blocks on the second row and so on.

In the case of a three column layout, the blocks contain a columnIndexHint field which indicates the preferred column for this block. In this case the blocks should be placed in the correct column using the value of the hint and then ordered top-to-bottom within the column using the order the blocks are contained within the page.

Markdown fields

Some fields in the API have both a Markdown and a HTML or plain text equivalent. It is only possible to update the Markdown versions of these fields. The other versions will be automatically updated to reflect the latest changes in the Markdown version.

Activities & paging

As the activity overviews are constantly updated, paging and retrieving new items are non-trivial problems. To solve this, we have the before and since parameters, which can be used for both paging and checking and retrieving only new activities. The response will also contain a remainingNumberOfActivities property, which will be 0 if there are no more pages. The activity calls will always return the newest X elements available first in newest first order.

Initial request

If it's the first time you request elements from an activity overview, you don't need to provide a value for either the before or sicne parameters. By default you will only get the latest activities in the activity overview you requested. If there more activities in the overview than could be returned in the initial page, the remainingNumberOfActivities property of the response will be greater than 0.

Paging

If you would like to retrieve more elements than provided in the first page, you need to provide the before parameter. As this parameter is exclusive, it should be set to the timestamp of the oldest activity that you have encountered.

For example, if my initial request retrieves a page containing A3, A2 and A1 (where A1 is the oldest and A3 is the newest), then you should use the timestamp of T1 as the before parameter to request the second page. For subsequent pages this can be repeated by taking the timestamp of the oldest activity in the last page, if there are more pages available.

Checking for new activities

The since parameter can be used to check for new activities. Like the before parameter, the since parameter is exclusive. To check and retrieve any new activities since the last activity encountered, the since parameter should be set to the timestamp of the most recent activity that was encountered.

If there are more new activities then the given maxItems, remainingNumberOfActivities will be larger than 0. In this case you can page through the new activities using the before parameter as above. The only difference is that you need to keep providing the same since parameter value in order to prevent from encountering duplicate activities.

For example, let's say we've previously encountered activities A1 through A4(with timestamps T1 through T4) and since then activities A5 through A10(with timestamps T5 through T10) have been added. If we have maxItems set to 2, to retrieve the new activities, we would need to perform the following requests:

Request number Parameters Response
1 since=T4&maxItems=2 activities = [A10, A9], remainingNumberOfActivities = 4
2 before=T9&since=T4&maxItems=2 activities = [A8, A7], remainingNumberOfActivities = 2
3 before=T7&since=T4&maxItems=2 activities = [A6, A5], remainingNumberOfActivities = 0

Errors

In the case of an invalid input error, the API will return a status code of 400 with an error object in the body with an error message. This error object only has a single field called errorMessage, which contains a description of the problems encountered with the request.

Try the API out

If you'd like to try out the API or experiment with it, you can do so on our API call page. In order to use this page, you need to enter your API token and click explore. A good place to start are the calls under the pages tag, which return lists of pages. Please note that any changes made using this page are permanent and will be directly reflected on your ZEEF pages!

Version history

New/changed in 2015.4

  • Included the URLs of both the page image and the page banner image (early access feature) with the page itself
  • Included favicon URLs for each link
  • Activity overviews are now available through the API
  • FIXED: some links had missing titles, link titles will now always be included correctly
  • DEPRECATED: Text and image blocks have been deprecated, you can still update old blocks, but you cannot add new blocks of these types to your page.

New/changed in 2015.3

  • A call was added to create pages.
  • There are now calls to view all pages for a given region, with the option to only return a certain type of pages
  • On an overview of multiple pages, the user's profile image will be used if there is no page image
  • API calls were added for the new link scratch pad

New changed in 2014.12

  • Links now have a popularity ranking field to indicate the popularity of a link relative to the other links in the same block. A lower popularity ranking value means a more popular link.

New/changed in 2014.11

  • Link blocks now contain a linkOrder field to indicate the order the links prefers the links to be displayed in. The links in the link block will be ordered in the API output in accordance with the value of this field.
  • Deprecated.

    Deprecated:

    {{baseUrl.value || ' '}}
       {{role}}{{$last ? '' : ', '}}

    Body

    Accept:
    no type

    Returns

    Content-Type:
    no type

    Response Headers

    Status codes



  • Interfaces not documented

    MireDot believes that the Java methods below correspond to REST interfaces, but somehow had problems parsing/processing these interfaces and therefore excluded them from the generated documentation. We would very much appreciate it if you would send us the interfaces (not the implementations) and the types used (returntype, parameters). This will allow us to further improve MireDot and better document your interfaces in the future.

Below is a list of potential problems detected by MireDot. They can be severe or not. Some of them wil result in low quality documentation, some are real implementation issues. With each warning, the Java method causing the problem is documented.

    • method:

    not shown here because this documentation was generated by the free version of MireDot. As such, not all features are supported.