Difference between revisions of "Public API"
| Line 1: | Line 1: | ||
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|API modules]]. | 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|API modules]]. | ||
Note that it is somewhat uncommon to directly use the API. Most of the time people use [[Loop]], Content and occasionally webRequest. | Note that it is somewhat uncommon to directly use the API. Most of the time people use [[Loop]], [[Forms]], [[Content]] and occasionally webRequest. | ||
The controllers themselves are extendible - for example if you wanted /v1/user/say-hello to exist, you can do so without editing the underlying default UserController as it is a partial class. Controllers for entity types, which is to say for most parts of a typical SocialStack API, have some common endpoints which are as follows: | The controllers themselves are extendible - for example if you wanted /v1/user/say-hello to exist, you can do so without editing the underlying default UserController as it is a partial class. Controllers for entity types, which is to say for most parts of a typical SocialStack API, have some common endpoints which are as follows: | ||
Revision as of 16:24, 8 March 2023
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.
Note that it is somewhat uncommon to directly use the API. Most of the time people use Loop, Forms, Content and occasionally webRequest.
The controllers themselves are extendible - for example if you wanted /v1/user/say-hello to exist, you can do so without editing the underlying default UserController as it is a partial class. 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"]}
- 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
