Setup API

Stackpress API is a configuration that ultimately act as gateways to events. The API follows the 2-legged and 3-legged OAuth 2.0 specifications. It also includes a webhook system that allows you to call external URLs when certain events happen.

1. API Config

Update the configuration file with the settings using the following as a guide.

❐ Copy

The API config includes the following options.

Option	Notes
	When API sessions expire. This is used with created column in the session table.
	Map of scopes to be used with the API following the OAuth specificaitons.
	List of API endpoint configurations.
	List of webhook configurations.

2. Configure Scopes

Scopes are used to limit access to certain endpoints and can be toggled per application. Let's update the confifguration with the following scope.

❐ Copy

The scope configuration, mainly used for documentation purposes, are as follows.

Option	Notes
	Readable friendly name of the scope.
	Readable friendly description of the scope.

NOTE: Scopes work in conjunction with the . The configuration itself is mainly for documentation purposes.

3. Configure Endpoints

API endpoints over configuraton act as a gateway that collects the input, calls events and returns its response. Update the confifguration with the following configurations.

❐ Copy

The above configuration allows for searching profiles, accessing a profile, and session. Searching profiles is open for anyone to use, while accessing a profile, and session require tokens. In order to test, the client tokens can be acquired through the following command.

❐ Copy

NOTE: If you got an empty result, see Populating database.

Each endpoint configuration requires the following parameters.

Option	Notes
	The HTTP method to listen to.
	The route pattern to listen to.
	• - An open endpoint that does not require any tokens. • - An endpoint that requires a client token for GET endpoints and a client token/secret for anything else. (2-legged) • - An endpoint that requires a session for GET endpoints and a token/secret for anything else. Auto populates the in the request data based on the session. (3-legged)
	A list of scope names that can access this endpoint.
	The name of the event to emit when the endpoint is requested.
	An object of static data that will add to and override the input keys (if they exist).

4. Custom Endpoint

The last endpoint in the section above configuration calls an event called . Let's create a custom event that will return a hello message. The event will be called when the endpoint is called.

❐ Copy

NOTE: Make sure to add the plugin to the list in the file.

The above code is a plugin file that listens to the event. It gets the from the request data and calls the event to get the profile. If the profile is found, it returns a hello message with the name of the profile. If not, it returns an error message.

NOTE: In order to test this, you need to populate the session table first. You can also use the command line to populate using the or database event.

5. Configure Webhooks

Webhooks are automated notifications sent from one application to another when a specific event occurs, like a new order, a user signup, or a payment transaction. They act as a lightweight, event-driven communication method, similar to reverse APIs. Instead of constantly polling for updates, the receiving application gets notified instantly when something happens in real-time.

❐ Copy

Each webhook configuration requires the following parameters.

Option	Notes
	The event to listen to.
	The external URL to call when the event is triggered.
	The HTTP method to use when calling the URL.
	Checks the results of the event against the validity object. If the results are not valid, the webhook will not be called. The validity object is a map of keys to values. The keys are the names of the columns in the results object. The values are the values to check against.
	Data to include in the results of the event. This adds and overrides the output keys (if they exist).

WARNING: Calling an internal URL may cause an infinite loop if the event listening to is emitted in the internal URL.