Biorn Wizard

Whenever a resource is called, the version of the method must be indicated via the " Biorn-API-Version " header, which is a decimal number such as 1.2 or 3.14.

Biorn will always look for the most recent version of each method relative to the version provided in the header.

This means that if, for example, version 3.14 is specified in the header for a Delete operation of a particular resource, the function to be executed will be: "delete_v3_14". If it does not exist, it will look for: "delete_v3_13", and if that does not exist, "delete_v3_12", and so on.

Below it is necessary to specify, for each of the basic operations ( c reation, r eading, u pdating, and d eletion of instances), when a session will be automatically initiated. The cases are:

Always: it is essential that the call contains an authentication token, and it will be verified. If the verification fails, the execution will be interrupted, and the operation will not be carried out
Never: even if the call contains an authentication token, it will be ignored, and therefore, Biorn will not attempt to start an API session
Only if the authentication token is sent: if the call contains an authentication token, it will be verified, and if the verification fails, the execution will be interrupted, and the operation will not be carried out

To indicate which custom commands need to initiate a session, you will have to specify this once the REST resource's PHP file is generated. For example, if there is a custom command called password reset request and we want its creation operation not to initiate a session, we will need to add "password_reset_request_v1_0" to the "aMethods_not_start_API_session" array in the REST resource's PHP file

It is important that you have already configured the languages that the responses of the API you are designing will use. This is done through the AVAILABLE_API_LANGUAGES constant in the configuration file located in: /Biorn/Configuration/configuration.php. Depending on the languages you have chosen, you will have different options at the current step.

Basically, there are two ways to approach translations in Biorn:

Using the translation file located in: /Biorn/Translations/translations.csv. This is recommended for multilingual APIs, meaning those that can respond with error messages in different languages. In this case, you will need to specify here the translation key and, in the translations file, indicate the human-readable value for each language
Using literal translations (without a language file). This is recommended for monolingual APIs, such as the typical case of an API that only responds in English

The human-readable value is used to auto-generate error messages when, for example, expected parameters were not sent or when they do not comply with validation rules. Thanks to this principle, you do not need to write all the error messages that the API could generate with the input parameters: they are generated automatically.

Here are some practical examples of human-readable values for easy understanding:

Column artist , suggested human-readable value: artist's name
Column genre , suggested human-readable value: musical genre
Column title , suggested human-readable value: title
Column collectionitem_id , suggested human-readable value: collection item ID

professor_id :

Processed on:

Must exist on:

Can be used in filter_by and sort_by URL parameters

Hide from JSON response in Read operations

Encrypted

Description (for OpenAPI documentation):

Example values that this attribute can take (for OpenAPI documentation) :

Type (for OpenAPI documentation) :

Validation rules

Existing reference in professor.id

Can be NULL

Integer with a minimum value of and a maximum value of

Can be NULL

Show verbose error

You can use the constants: TINYINT_min_value, TINYINT_max_value, UNSIGNED_TINYINT_max_value, SMALLINT_min_value, SMALLINT_max_value, UNSIGNED_SMALLINT_max_value, MEDIUMINT_min_value, MEDIUMINT_max_value, UNSIGNED_MEDIUMINT_max_value, INT_min_value, INT_max_value, UNSIGNED_INT_max_value, BIGINT_min_value, BIGINT_max_value and UNSIGNED_BIGINT_max_value. You can also put the number in string format by enclosing it in double quotes (for example: "76042004635195631092204844616388157257"), this can be useful for manipulating very large numbers

None

year :

Processed on:

Must exist on:

Can be used in filter_by and sort_by URL parameters

Hide from JSON response in Read operations

Encrypted

Description (for OpenAPI documentation):

Example values that this attribute can take (for OpenAPI documentation) :

Type (for OpenAPI documentation) :

Validation rules

Integer with a minimum value of and a maximum value of

Can be NULL

Show verbose error

None

Biorn allows filtering and sorting of instances in CRUD operations for Read, Update, and Delete through the filter_by and sort_by URL parameters (respectively)

By default, filters and sorting can only be applied to columns of the same table that represents the REST resource, although cross-table filters and sorting can also be enabled. Let's take a closer look at this:

Cross-filterning :

For example, suppose we have the following 2 classes:

• CollectionItems (id, regular_user_id, album_id...)
• Albums (id, artist, title...)

By default, the Read method of CollectionItems only allows to apply filters to the columns of the same CollectionItem table. For example, if we want to list the album collection of the user who has id 5, we will have to make the call:

GET /collection-items?filter_by=regular_user_id[equal]='5'

Given the above collection, if we now want to display only the results whose album meets one of the following 2 conditions:

• Its artist contains the word "crimson"
• Its title contains the word "crimson"

we could not, because the "artist" and "title" columns do not belong to the "collection_item" table but to the "album" table

Enabling cross-filtering allows to add this functionality. The call will be:

GET /collection-items?filter_by=regular_user_id[equal]='5' AND (album.artist[contains]='crimson' OR album.title[contains]='crimson')

Cross-sorting :

For example, suppose we have the following 2 classes:

• CollectionItems (id, regular_user_id, album_id...)
• Albums (id, artist, title...)

By default, the Read method of CollectionItems only allows to sort the results using the fields of the same CollectionItems class. For example, if we want to list the album collection of the user who has id 5, we will have to make the call:

GET /collection-items?filter_by=regular_user_id[equal]='5'

Given the above collection, if we now want to sort the results by album's title, we could not, because the "title" column do not belong to the "collection_item" table but to the "album" table

Enabling cross-sorting allows to add this functionality. The call will be:

GET /collection-items?filter_by=regular_user_id[equal]='5'&sort_by=album.title(ASC)