API Documentation

Concepts

CMS has five entities:

  • Users
  • Spaces
  • Content Types
  • Web Hooks
  • Contents

Users can be associated with many spaces. Spaces can be associated with many users. It's a many-to-many relationship. A space is a "backend" for the content of a single application. For example, a space represents a single website or a single mobile application.

A space can "own" many content types, one-to-many.

A content types is a taxonomy of content. For example, if you're familiar with the content management system WordPress, a content type here is akin to categories, tags, posts, or pages on WordPress.

A content type "owns" many content instances, one-to-many.

This is where CMS begins to differ from many other content management systems and content management infrastructures. In CMS concepts such as categories, tags, posts, and pages are on the same hierarchy. Where in other content management systems, such as WordPress, categories and tags exist on a level above posts and pages.

Another very important distinctions: CMS does not provide you a rigid set of content types. You define content types and within content you define their relation to other contents. Meaning: if you choose to create a WordPress type heirarchy in CMS you would define the content types pages and posts that would have two fields: a category field which would be a Reference field type and a tags field which would be a ReferenceList field type. You would then create your two additional content types, categories and tags, then when creating content under pages and posts, you would choose what they are referencing.

This is the biggest feature of CMS for me: arbitrarily many and arbitrarily deep connections from one content instance to another content instance or list of content instances. Creating content in CMS should not restrict your data model.

Web hooks are used when you want your application to respond to content within CMS under your space being created, updated, and deleted on the fly. For doing any cache breaking or other you may want to do within your application.

Using the API

Before diving into the API I suggest you poke around the user interace and test drive creating spaces, content types, and contents. To get a feel for the above concepts described.

You'll also need an account to interact with the following APIs. The APIs use basic authentication for client applications. Sign ups are available to anyone but CMS is currently in a limited public alpha. Meaning: all your data is automatically deleted on a 15 minute interval. CMS currently doesn't have any way to fight abuse. Once CMS' story on fighting abuse has been improved CMS will be moved into beta or general availability. If this is an inconvenience I urge you to look into self-hosting CMS. All you need is read access to the repository (which you already have), a Go compiler, and a MySQL database.

Spaces API

Five methods are available to the Spaces API.

  • POST: Create a Space.
  • GET: Retrieving a Space.
  • PATCH: Update a Space.
  • DELETE: Remove a Space.
  • PUT: Copy a Space.

POST: Create a Space.

curl -s -u "$cmsuser:$cmspass" https://cms.evanjon.es/space
          -X POST -F name="cURL test" -F desc="Some description here"

You'll be returned JSON that will have a redirectURL. The ID of the created space will be inside. You'll use the space ID to GET, PATCH, DELETE, and PUT the space.

GET: Retrieving a Space.

curl -s -u "$cmsuser:$cmspass" https://cms.evanjon.es/space
          -X GET -F space=29

When you GET a Space you'll also retreive a paginated list of Content Types under the Space. The API returns JSON. Under the key "ContentTypes" you'll see a few more key/values: "ContentTypeList", "ContentTypeListMore", and "ContentTypeListBefore". Use the query parameter "?before=$ID" on your GET request to retrieve the next page of results, to use in conjunction with "ContentTypeListBefore". If another page of content type results exists "ContentTypeListMore" will state so with its boolean value.

PATCH: Update a Space.

curl -s -u "$cmsuser:$cmspass" https://cms.evanjon.es/space
          -X PATCH -F space=29 -F name="cURL test (update)"

DELETE: Remove a Space.

curl -s -u "$cmsuser:$cmspass" https://cms.evanjon.es/space
          -X DELETE -F space=29

PUT: Copy a Space.

curl -s -u "$cmsuser:$cmspass" https://cms.evanjon.es/space
          -X PUT -F space=30 -F name="cURL test copy" -F desc="This is a copied space"

Please note: copying a space copies all of the space's content types and content instances.

Content Types API

Four methods are available to the Content Types API.

  • POST: Create a Content Type.
  • GET: Retrieving a Content Type.
  • PATCH: Update a Content Type.
  • DELETE: Remove a Content Type.

Web Hooks API

Four methods are available to the Web Hooks API.

  • POST: Create a Web Hook.
  • GET: Retrieving a Web Hook.
  • PATCH: Update a Web Hook.
  • DELETE: Remove a Web Hook.

Content API

Four methods are available to the Content API.

  • POST: Create a Content.
  • GET: Retrieving a Content.
  • PATCH: Update a Content.
  • DELETE: Remove a Content.