API Modules

A newly regularly generated API module has 5 files. Assuming you did socialstack generate Api/Things, here's what each of them is for:

Events.cs

When something happens in your API, an event is triggered. By default all entities have a common set of events for things like creation/ updates/ deletion etc, but it can be extended by defining a custom event type. This is detailed more on the page about events. One of the core goals of events in SocialStack is for them to be extremely fast and also easy to use with IDE autofilling, so these auto generated files exist to enable those statically typed naming in the form of Events.Thing.BeforeCreate and so on.

Event handlers, including for a services own content type, are typically added inside service constructors.

Thing.cs

This is the entity description file. It describes what fields are on the entity. In a nutshell, fields are stored in the database and properties are not. There are some conveniences around field naming which is described on the entities page.

ThingService.cs

The service, a singleton (instanced once at startup), is used for getting/ listing/ deleting/ updating/ creating an entity. For example if you want to get hold of a user's information, you would ask the UserService. Services support C# dependency injection but can also be obtained via Services.Get<UserService>(), with Services in the Startup namespace.

Often, event handlers are placed inside the service's constructor in order to validate your entity or e.g. add custom field values to it whilst it is being created. It's very common for e.g. ThingService to have Events.Thing.BeforeUpdate and so on inside its own constructor - this allows flexibility in the form of other modules actually unregistering those handlers, if it has a goal of heavily overriding default behaviours.

ThingController.cs

Controllers are the web API endpoints and effectively represent the main user facing frontage of your site. Just like with services, the controllers have a series of common convenience endpoints which are usually accessed with webRequest or Loop on the frontend.

Permissions.cs

This file is used to define the installable, base permissions for your module. It should represent the most common scenario that you expect to happen. For example, password resets should never be publicly visible - and that is going to be quite universal on most websites. These base permission grants can however be overridden in the admin panel, or with other event listeners. When creating permission grants in code, they should target the core roles, particularly if the intent is to make a portable module which can be copied or installed easily on to other projects.

For more information on what the roles are and how the grants work, take a look at the permissions article.