Public API

SocialStack API's (the C# binary) have a REST web API whose available endpoints originate from the set of controllers in the project. For more detail on the controllers, see the page about API modules.

The controllers themselves are extendible - for example if you wanted /v1/user/say-hello to exist, you can do so without editing the underlying ThirdParty default UserController as it is a partial class. See custom endpoints for more general details on how to create new endpoints.

Usage from Javascript/ Typescript

Loop and graphs created with the Graph Editor are common ways to access data. Graphs are particularly useful when you have content types that do not exist at compile time, and Loop is great for typical lists of content. Sometimes though you will be wanting to use custom endpoints or have more control over the loading and display of your content in which case you would use the public API from your Javascript or Typescript frontend files.

import userApi from 'Api/User';

...

userApi.list().then(userSet => {
    console.log(userSet.results);
});

Common API structure

If you want to call the web API externally such as via a standalone tool or another web service, controllers for entity types, which is to say for most parts of a typical SocialStack API, have some common endpoints which are as follows:

In all cases if you don't have permission, it will error on you.

• GET /v1/thing/list - Lists everything of this entity type.

• POST /v1/thing/list - Lists based on a POSTed filter, where the post payload is:

{"query":"Token=?", "args":["the-token-value"]}

It can also contain pageSize, pageIndex, sort and includeTotal to fine tune the list.

{"query":"Token=?", "args":["the-token-value"], "pageSize": 10, "pageIndex": 0, "includeTotal": true, "sort": {"field": "Name", "direction": "asc"}}

Including the total will return the total number of results when you are receiving a partial set of them, for example because you are specifying a page size which is less than the total number of matches.

• POST /v1/thing - Creates a new entity of the given type. The payload is simply the fields and properties of the entity.

Properties are set as well if you need some more advanced temporary values. This is used by, for example, "password" on User which is not directly stored but instead a hash of it is.

• POST /v1/thing/14 - Where 14 is an ID. Updates the entity with the given ID. The payload is the same as for creation.

• DELETE /v1/thing/14 - Deletes the given entity by its ID. Returns the entity as it was just before it was deleted.

• GET /v1/thing/14 - Loads a single item by its ID. This is what <Content> uses internally, via webRequest.

Includes

Includes are a mechanism in SocialStack for getting related data in the same API call. They are available on core endpoints such as load and list, and are simply a query string parameter of the includable fields that you would like to obtain.

GET /v1/thing/14?includes=creatorUser

If you're not sure what includes the API currently has, you can use a wildcard:

GET /v1/thing/14?includes=*

If there is more than one that you would like, they are comma separated:

GET /v1/thing/14?includes=creatorUser,tags