Table of Contents

header.png

1. 200ok alephDAM

This is the service documentation for the 200ok Gmbh product alephDAM. It is intended for developers and system administrators working with alephDAM.

alephDAM allows you to integrate news from content providers into your site. You can automatically deliver tens of thousands of articles, videos, and images every day - based on rules that you configure. Manage your assets with a single point of integration and configuration instead of dealing with many vendors.

alephDAM seamlessly integrates into your existing workflows. It works with your CMS, ePaper, print, and archive systems.

For more general information see https://200ok.ch/alephdam.html, read our PDF document brief description (German) or schedule a demo by writing to info@200ok.ch.

1.1. Feedback

Please let us know about gaps or errors in our documentation at info@200ok.ch.

1.2. High level architecture diagram

Let's begin with the 50'000ft view of alephDAM. It's a good entry point into understanding the basic concepts.

architecture-diagram-highest-level.png

2. API

For ingesting data, alephDAM offers three protocols:

2.1. FTP

FTP is the industry standard to ingest news. Even though FTP is rather old technology, our FTP servers are not just robust, but also modern and event oriented. As a customer, you can just upload your data via FTP and leave the rest to alephDAM - your data will be processed within milliseconds.

2.2. S3

You can upload your data to an AWS S3 bucket. Your data will be processed in an event oriented manner using AWS SNS.

2.3. HTTP REST

alephDAM has an original HTTP REST API. It is documented with the industry standard OpenAPI Swagger - a sample instance is available at .

Here is an overview of the resources that can be managed via the HTTP REST API:

swagger.png

2.3.1. Example requests

  1. Documents

    These two endpoints are relevant for managing documents:

    • Creating new documents: POST /api/v1/{tenant}/documents
    • Getting information on a document: GET /api/v1/{tenant}/documents/{uuid}

    Let's first create a new document which should resemble a video. It optionally takes misc metadata. The absolute minimum to ingest a new video are:

    • source_url: HTTP accessible URL from where alephDAM can download an asset.
    • type: Everything ingested in alephDAM is a 'document'. In the case of creating a video document, the type would be "video".
    • identifiers: The 'identifiers' from the upstream document. The type of these identifiers will vary across agencies, products and types. The first identifier will be used to identify documents and subsequent updates of the same document. It serves as a foreign key.
    • title: The 'title' of the upstream document.

    There are a lot more options for setting metadata, including poster images. For ease of use, we'll be doing an minimal example here. For more information on the available metadata, please see .

    Here's what the request would look like using the popular httpie cli tool:

    http --ignore-stdin --pretty format \
         'https://api.aleph-bluewin-dev.200ok.ch/api/v1/bluewin/documents?token='${auth_token} \
         identifiers:='["my_key_321"]' \
         title="Demo Video" \
         type="video" \
         language="de" \
         source-url="https://200ok.ch/alephdam_fixtures/1234/mars.mp4"
    
    {
        "identifiers": [
    	"my_key_321"
        ],
        "language": "de",
        "observed-datetime": "2022-05-12T09:42:25.236Z",
        "source-url": "https://200ok.ch/alephdam_fixtures/1234/mars.mp4",
        "title": "Demo Video",
        "type": "video",
        "user": "lsi",
        "uuid": "78f19dd7-8591-47ef-8445-9dd7338976a6",
        "workflow": "process.lsi.application.json"
    }
    

    Here's what such a request would look like in Swagger:

    swagger_post_document.png

    Now you have created a document in alephDAM and received a response with minimal information to later make queries on any updates regarding the document.

    The document will now be processed in the background. To make further inquiries on the document, you can make subsequent requests. For that, you can use the unique identifier of the document, the uuid.

    Here's how to receive information on this document, including the video URL and ID on Brightcove:

    http --ignore-stdin --pretty format \
         'https://api.aleph-bluewin-dev.200ok.ch/api/v1/bluewin/documents/'${document_uuid}'?token='${auth_token}
    
    {
        "agency": "lsi",
        "asset-size": null,
        "author": null,
        "bc-backlink": "https://studio.brightcove.com/products/videocloud/media/videos/6305secret",
        "bc-id": "6305980805112",
        "catchline": null,
        "categories": null,
        "complete": true,
        "created-at": "2022-05-12T09:33:09.889Z",
        "errors": [],
        "exported": null,
        "genres": null,
        "id": 3496049,
        "identifiers": [
    	"my_key_321"
        ],
        "images": [],
        "keywords": null,
        "language": "de",
        "li-backlink": null,
        "locale": "de",
        "locations": null,
        "product": null,
        "published-datetime": null,
        "ready": true,
        "source-url": "https://200ok.ch/alephdam_fixtures/1234/mars.mp4",
        "special-rules": null,
        "teaser": null,
        "text": "",
        "title": "Demo Video",
        "type": "video",
        "updated-at": "2022-05-12T09:33:12.180Z",
        "urgency": null,
        "urn": "urn:lsi:video:my_key_321",
        "uuid": "3b3e8307-4a0c-4871-88a1-631df09e5154",
        "version": null,
        "video-state": null,
        "workflow": "process.lsi.application.json"
    }
    

    Here's what such a request would look like in Swagger:

    swagger_get_document.png

    If there is any error on uploading the video to Brightcove, extensive information will be added to the error field. For example:

    "errors": [
      {
        "type": "export-video-to-bc",
        "message": "Create video request failed",
        "cause": "Reference id urn:lsi:video:1234 is already in use."
      }
    ]
    

Author: 200ok GmbH

Created: 2022-05-12 Thu 15:40

Validate