API testing

It is recommended to always test your calls to confirm they are working as intended before running them against your production assets. The Orange Logic platform offers the following features to test APIs:

• Backup site: Each instance of Orange Logic has a backup site. If you are making a very large number of API calls, consider working in the backup site to avoid any performance issues that might affect other test site users. Submit a support request and confirm your testing plan with Orange Logic staff before working in the backup site or making large batches of API calls.
• Test site: Some Orange Logic plans include a dedicated test site, which you can use to try out new features, configure new workflows, set up new integrations, and test APIs. Your production site database is regularly copied to your test site, which allows you to try out new endpoints before your changes impact users or alter live data. For more information about test sites, review the Assets in test environments article and Test environment FAQs.
• Personal folders: By default, each user has a personal folder in the Personal Folders directory. This directory is separate from the Library folder, which is the root folder for all sub-folders and assets. You can upload test assets to your personal folder and test calls against them.
• Parameter sessions: You can create parameter sessions to test new workflows and configurations. When you are working in a session, your changes are only visible in that session, which means you can test configurations without impacting other users.

❗

Warning

Parameter sessions only isolate changes to parameters. A parameter is any setting that controls how your instance of Orange Logic works or looks. Examples of parameter changes include creating a new metadata field, changing the layout of an asset subtype, changing an asset’s action buttons, and replacing the site logo.

Changes to database objects are not limited to sessions and are visible to other users. Database objects include assets, groups, tags, and user accounts. Here are some examples of changes that all users will see (if they have the required privileges):

• Uploading a new asset.
• Renaming an asset.
• Creating a folder.
• Deleting a group.
• Creating a new tag.
• Creating a user account.

ℹ️

Note

Authentication tokens are valid for only one server. Therefore, when your Orange Logic site switches from one server to another, you must reauthenticate to continue running APIs. A single environment might rely on multiple servers, and an authentication token is valid for only one site and one server.

Create API accounts

Before you can begin running and testing APIs, you must have an Orange Logic account. If you can’t create user accounts yourself, contact your Orange Logic administrator.

Typically, organizations create a single account with a shared email address that any individual working with APIs can access. In addition, we recommend creating an account for each specific API use case. For example, you might create an Adobe Integration API User account in addition to your general-use API account.

After you’ve completed your initial testing and you’re ready to move your API setup from your test environment to your production environment, you’ll re-create your API user accounts in prod. Rebuilding the API-related accounts gives you an additional opportunity to confirm that the accounts have the appropriate Security Functions and Permissions.

Orange Logic Security Functions and Permissions

Security Functions and Permissions determine which APIs a user can run and which assets a user can work with.

• Security Functions determine whether a user can perform a certain action or access a specific feature. For example, a Security Function allows a user to upload assets.
• Permissions grant access to assets and determine what a user can do with an asset (download, edit, share, delete, etc.).

To call an API, users need the Security Functions to complete the relevant actions, such as uploading assets or generating links. In addition, some APIs have unique Security Functions. For example, to run the Search API, users need the Access to the search API Security Function.

ℹ️

Note

Most users who run APIs should be assigned the Can bypass new device login verification Security Function. This Security Function allows the user to log in to and interact with Orange Logic without needing to complete the new device verification step.

API users need Permissions to access assets via API, just as they would to access those assets in the Orange Logic interface. For example, the Search API returns only assets that a user has Permissions to view, and the Upload APIs allows users to upload assets only to containers they have Permission to edit.

Administrators should carefully consider which actions API users need to complete and assign Security Functions and Permissions accordingly. A user account can be a member of multiple groups, so you can separate Security Functions and specific asset Permissions into discrete groups for ease of management. Alternatively, administrators can create accounts for API users and add them to the *SuperAdmin group, which is granted full access to all Security Functions and Permissions.

If calling an API results in unexpected access errors, ask your Orange Logic administrator to check your Security Functions and Permissions to ensure you have the appropriate access.

API testing tools

Many Orange Logic API endpoints offer robust functionality that must be tested in a full API client, such as Postman. For example, DataTable APIs use unique query operators, such as ++, that can’t be used in basic API testing tools like Swagger.

Many API clients allow you to import the OpenAPI specification JSON, which you can find in Swagger.

• Access Swagger from the Orange Logic interface by going to Administration > Maintenance > APIs > Swagger UI.
• Go directly to Swagger by adding /swagger to the end of your Orange Logic URL. For example: [https://mangovations.com/swagger].
• Go directly to the JSON file by adding /swagger/application/swagger.json to the end of your Orange Logic URL. For example: [https://mangovations/swagger/application/swagger.json].

If you've logged in to Orange Logic and have active browser cookies, you can test simple API calls in Swagger or you can run basic GET calls directly in your browser.

ℹ️

Note

• If an incorrect authentication token and a correct session cookie are provided in the same request, the API uses the cookie.
• Swagger always uses session cookies, so you must log in to the Orange Logic interface to test APIs in Swagger.