Introduction

The Resource Query Language (or RQL) is used for querying and manipulating resources in the Marketplace Platform's REST API. With RQL, you can filter, sort, paginate, and project data. It is simple to use but flexible enough to handle complex scenarios.

Using RQL

RQL consists of a set of operators that can be classified into three main categories:

1. Comparison Operators: These perform comparisons like equals, greater than, etc.

2. Logical Operators: These combine multiple conditions.

3. Algorithmic Operators: These handle functionalities like sorting and pagination.

Operators are formatted as operator(arg1,arg2,...). Complex expressions can be created by nesting these operators.

Practical Examples

Suppose you want to list all users with a specific domain. Implementing filtering is essential, and this is where RQL comes in.

Basic Filtering

To display all users with the first name "Buzz", your GET request would look like this:

GET /v1/accounts/users?firstName=Buzz

the same expression can be written as:

GET /v1/accounts/users?eq(firstName,Buzz)

Sorting

To sort users based on their first name, your GET request would look like this:

GET /v1/accounts/users?order=firstName

To sort in the opposite direction, the '-' operator can be used:

GET /v1/accounts/users?order=-firstName

Pagination

To paginate your results with a limit of 10 users and to retrieve the third page (offset 20):

GET /v1/accounts/users?limit=10&offset=20

• The first parameter limit=10 expresses the number of users to return

• Second parameter offset=20 offsets the starting position in the result set. The first 20 users will be skipped.

Projection

To request specific fields, such as forstName, lastName, and email to be included, the select=+ operator can be used:

GET /v1/accounts/users?select=+firstName,+lastName,+email

To request certain fields to be excluded, the select=- operator can be used:

GET /v1/accounts/users?select=-firstName,-lastName,-email

Search

To search for all users with the firstName starting from 'Bu', the following query can be used:

GET /v1/accounts/users?ilike(firstName,Bu*)

the operator ilike performs a case-insensitive search.

Combining Operators

Logical operators can be used to combine multiple operators. For example, to filter users with first name "Buzz" and last name "Astral":

GET /v1/accounts/users?and(eq(firstName,Buzz),eq(lastName,Astral))

In simple cases, a combined expression can also be written in the following form:

GET /v1/accounts/users?firstName=Buzz&lastName=Astral

Operators

Advanced use cases

Special Characters in Values

To pass special characters (e.g., &^$?) or whitespaces as values to RQL operators, enclose them in either double quotes (") or single quotes (') as shown in the following example:

GET /v1/accounts/users?firstName="Buzz !!!"

If you need to include a quotation mark within the value, you can do so by enclosing it with a different type of quotation mark, as shown in the following example:

GET /v1/accounts/users?firstName="Buzz with the ' Quote"

Allowing you to pass these special symbols as values.

The Asterisk Character and the ilike operator

The asterisk (*) character has a special meaning in the ilike operator, matching zero or more characters in its place from the parameter value. For example, the "*dog" pattern will match strings like "big dog" and "dog," but it will not match "big dog!" because of the exclamation mark.

If you need to use the asterisk (*) character itself in the pattern, you can escape it as '*', as shown in the following example:

GET /v1/accounts/users?ilike(firstName,"The\**")

The ilike operator in this case will be searching for the literal value “The*” at the beginning of the firstName property.

Introduction

The Marketplace Platform REST API lets you interact with the platform programmatically. Our API is organized around REST, has predictable resource-oriented URLs, uses JSON-encoded representations, and uses standard HTTP response codes, authentication, and verbs. Use our API to create apps, automate tasks, or build integrations with the platform.

Beginners Guide

What is a REST API?

An API (Application Programming Interface) is a set of rules that allows programs to talk to each other and share data and functions in a standard format over the Internet.

REST (Representational State Transfer) is a way to design APIs for distributed systems. When people mention a "REST API", they mean an API that uses the HTTP protocol.

These URLs point to different resources, which can be data like JSON, web pages, audio files, or images. You can perform actions on these resources using HTTP methods like GET, POST, PUT, and DELETE:

• GET = Retrieve data

• POST = Create new data

• PUT = Update existing data

• DELETE = Remove data

For example, the Marketplace Platform offers several REST APIs for tasks like managing orders and viewing users and accounts. Each API in our platform works similarly, whether you access it directly over HTTP or through helper libraries in various programming languages.

Authentication

The Marketplace Platform uses API tokens to authenticate requests. You can view and manage your API keys in the user interface of your account settings. Include your API token in the "Authorization" HTTP header with the "Bearer" prefix for authentication.

For example, the following request could be used to retrieve a list of Buyers:

GET https://api.platform.softwareone.com/public/v1/accounts/buyers
Authorization: Bearer {TOKEN_VALUE}

Your API keys have permissions assigned to them, so keep them secure. Do not share your secret API keys in public areas like GitHub or client-side code.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Content Type

The Marketplace Platform API expects the content type of API requests to be "application/json" in most cases (except for cases where "multipart/form-data" is used to send attachments)

GET https://api.platform.softwareone.com/public/v1/accounts/buyers
Authorization: Bearer {TOKEN_VALUE}
Content-Type: application/json

To communicate successfully with the Marketplace Platform APIs, ensure your API requests are formatted using the "application/json" content type. Using the wrong content type may result in unexpected behavior or errors.

API Endpoint

The base endpoint for the Marketplace Platform API is:

https://api.platform.softwareone.com/public

All API requests start from that base URL. For example, if you have an endpoint like:

/v1/accounts/buyers

The fully qualified URL that you need to use is:

https://api.platform.softwareone.com/public/v1/accounts/buyers

Use this base endpoint with specific API paths to correctly access the resources and services provided by the Marketplace Platform.

Resource Query Language

The Resource Query Language (or RQL) is used for querying and manipulating resources in the Marketplace Platform's APIs. With RQL, you can filter, sort, paginate, and project data. It is simple to use but flexible enough to handle complex scenarios.

For example, to display all users with the first name "Buzz", your GET request would look like this:

GET /v1/accounts/users?firstName=Buzz

See Resource Query Language for more details.

Errors Handling

Our platform reports errors using HTTP status codes in a standard format, ensuring consistency and clarity. For more details, please see Errors Handling.

Explore the APIs

Enable the previously disabled object.

When enabled, the account status will change to Active if the account has ExternalId assigned or Enabled otherwise.

Account Object

The account object represents an individual account on the Marketplace platform. This object contains the following properties:

Example

When enabled, the buyer status will change to Active if the buyer has ExternalId assigned or Enabled otherwise.

Buyer Object

The buyer object represents an individual buyer in the Marketplace platform. This object contains the following properties:

Example

{
	"id": "BUY-3911-2313",
	"href": "/accounts/buyers/BUY-3911-2313",
	"contact": {
		"name": "Will Smith",
		"firstName": "Will",
		"lastName": "Smith",
		"email": "will.smith@adastraflex.com",
		"phone": null
	},
	"externalIds": {
		"erpCompanyContact": "WW-CON-123456",
		"erpCustomer": "WW-SCU-123456"
    },
	"status": "Active",
	"icon": null,
	"address": {
		"addressLine1": "PO Box 31",
		"addressLine2": "Victory Road",
		"postCode": "DE24 8BJ",
		"city": "Derby",
		"state": "Derbs",
		"country": "UK"
	},
	"taxId": "VAT1",
	"name": "Stark Industries"
}

{
	"id": "BUY-3911-2313",
	"href": "/accounts/buyers/BUY-3911-2313",
	"contact": {
		"name": "Will Smith",
		"firstName": "Will",
		"lastName": "Smith",
		"email": "will.smith@adastraflex.com",
		"phone": null,
		"user": {
			"id": "USR-0000-0001",
			"href": "/users/USR-0000-0001",
			"icon": null,
			"invited": "2024-02-03T11:34:15.381Z",
			"joined": "2024-02-04T12:34:15.381Z",
			"lastLogin": "2024-02-05T13:34:15.381Z",
			"name": "Will Smith"
		}
	},
    "externalIds": {
		"erpCompanyContact": "WW-CON-123456",
		"erpCustomer": "WW-SCU-123456"
    },
	"status": "Active",
	"icon": null,
	"address": {
		"addressLine1": "PO Box 31",
		"addressLine2": "Victory Road",
		"postCode": "DE24 8BJ",
		"city": "Derby",
		"state": "Derbs",
		"country": "UK"
	},
	"taxId": "VAT1",
	"account": {
		"id": "ACC-5563-4382",
		"href": "/accounts/accounts/ACC-5563-4382",
		"type": "Client",
		"status": "Active",
		"icon": null,
		"name": "AdAstraflexx"
	},
	"name": "Stark Industries",
	"sellers": [
		{
			"id": "SEL-1299-2079",
			"href": "/accounts/sellers/SEL-1299-2079",
			"externalId": "SWO_CH",
			"name": "SoftwareOne AG"
		}
	],
	"audit": {
		"created": {
			"at": "2023-12-14T13:44:20.896Z",
			"by": {
				"id": "USR-0000-0001",
				"href": "/users/USR-0000-0001",
				"icon": null,
				"invited": "2024-02-03T11:34:15.383Z",
				"joined": "2024-02-04T12:34:15.383Z",
				"lastLogin": null,
				"name": "Will Smith"
			}
		},
		"updated": {
			"at": "2024-01-06T19:04:16.692Z",
			"by": {
				"id": "USR-0000-0001",
				"href": "/users/USR-0000-0001",
				"icon": null,
				"invited": "2024-02-03T11:34:15.383Z",
				"joined": "2024-02-04T12:34:15.383Z",
				"lastLogin": null,
				"name": "Will Smith"
			}
		}
	}
}

Seller Object

The seller object represents a seller in the Marketplace platform. This object contains the following properties:

Example

Get a single Seller object by ID.

Get the Sellers collection.

Update the seller object, except the seller status. Use the disable, activate, deactivate, and delete endpoints to manage the status.

Deactivate a seller.

When a seller is deactivated, the status changes from Active to Offline.

Delete the seller object. When deleted, the status changes from Active to Deleted.

Disable or deactivate the seller object.

When disabled, the status changes from Active to Disabled. Disabled sellers cannot be used in transactions.

Activate a previously deactivated or disabled seller.

When activated, the status changes from Offline or Disabled to Active.

Create a new Seller object.

Licensee Object

The licensee object represents a licensee in the Marketplace platform. This object contains the following properties:

Example

Get a single licensee object by ID.

Delete the licensee object.

Enable the previously disabled licensee object.

Create a new licensee object.

List Licensee items in the Licensees collection.

Update the licensee object.

You can update the licensee Seller Object, except the status (which is managed through the disable, enable, deleteendpoints) buyers id and sellers id.

Disable the licensee object.

Get a list of modules in the platform.

Set passwords for non-SSO users during onboarding.

Unblock a previously blocked user.

Block a user.

Get the user groups collection.

Get a single user by ID.

Update a user.

User Object

The user object represents an individual user in the Marketplace platform. This object contains the following properties:

Example

{
  "id": "USR-6375-2499",
  "href": "/v1/accounts/users/USR-6375-2499",
  "email": "test12.test@SWO1.com",
  "name": "John Smith",
  "firstName": "John",
  "lastName": "Smith",
  "status": "Invited",
  "phone": { 
      "prefix": "+34",
      "number": "660707172"
  },
  "accounts": [
		{
			"id": "ACC-1671-0642",
			"href": "/accounts/ACC-1671-0642",
			"icon": null,
			"name": "You Are a Test Account"
		}
  ],
  "group": [
      {
        "id": "UGR-5116-6265",
        "name": "Administrators"
      },
      {
        "id": "UGR-5116-6565",
        "name": "Fulfillment Managers"
      }
  ],
  "invitation": {
    "code": "910B14E6CB2343A09CB32F24BBC4BEF1",
    "status": "Invited"
  }
}

Module Object

The module object represents a module in the Marketplace platform. This object contains the following properties:

Example

{
  "id": "MOD-1234",
  "name": "Invoices",
  "description": "Invoices module",
  "accountTypes": ["vendor", "client", "operations"],
  "isEnabledByDefault": true,
  "isConfigurable": false
}

Delete a user group.

Create a user group for the client account.

Get a single user group by ID.

Get a single account user by ID.

Invite a user to the account.

Assign an account user to a specific group.

Get a list of all platform users.

Removes a user from a specific group.

Accepts user invitation to the account.

Deletes a user from the account. The user remains active in the other accounts.

Send new invitation when invite expires.

Create a new token object for the specific account.

Get all users assigned to an account.

Group Object

The group object represents a user group in the Marketplace platform. This object contains the following properties:

Example

Token Object

The token object represents an authentication token user in the Marketplace platform. This object contains the following properties:

Example