Register Resources in the Catalog

Last modified: November 28, 2024

Introduction

There are three ways to register published services in the Catalog. Mendix supports all OData versions, REST, Business Events, and Web Services

This how-to teaches you how to register a service in the following ways:

Prerequisites

Before starting this how-to, make sure you have completed the following prerequisites:

  • You have Studio Pro 8.14.0 or above installed
  • You have a Mendix account
  • You have an exposed OData/REST/Web service or Business Event that you are ready to register (for instructions on how to create an exposed OData service, refer to the sections on creating an app and exposing an entity in Share Data Between Apps

Registering a Service Through Mendix Cloud

If you have a published service that is deployed to Mendix Cloud, then your service is already registered in the Catalog.

Registering a Service Without Mendix Cloud

If you are not using Mendix Cloud to deploy your Mendix application, there are two other ways to register an exposed service in the Catalog:

The Catalog collects metadata about the application and environment where your application is deployed, so you can distinguish services from one another. To register your service, you need to provide details about both the application and the environment where the service is deployed.

For details on working with external entities and the Catalog without Mendix Cloud, see Register Services without Mendix Cloud.

Registering a Service Through the Catalog UI Form

The Catalog has a UI form where you can register a single exposed service. Make sure you have collected the following details before you begin:

  • Metadata contract file as an .xml, .json, .yaml or .wsdl, depending on the service you want to register, or a .zip if there are multiple files
  • Service details: Name, Version, Path
  • Application Name
  • Environment details: Name, Location (URL), Type

Follow the steps below:

  1. Open the Catalog home page.

  2. On the Contract screen, select what type of service you would like to register. Upload a valid contract file corresponding to the service type that is selected, such as:

    • .xml for OData
    • .yaml or .json for REST
    • .wsdl or .xml for Web Service

    For more information on the contract, see the Contract Structure section below.

  3. On the Service Details screen, select the type of service you want to register and specify the following details:

    1. Service Name
    2. Service Version
    3. Service Relative Path.

    The Service Relative Path is the path of the service contract relative to the environment URL of the application. For more information on versioning, see Semantic numbering. The other fields on the form are optional.

  4. Once you have filled out all the required fields, select Next.

  5. On the Application screen, select an existing application by name or register a new one. You will also be able to edit Technical Owner and Business Owner through the Curation feature after registration is completed.

  6. Once you have filled out all the required fields, select Next.

  7. On the Environment screen, select an existing environment by name, or provide the Environment Name, Environment Location (URL), and Environment Type to register a new one. The Environment Type options indicate what type of data you might find there:

    • Production – data is of production quality
    • Sandbox – the Mendix Free App environment, data is not of production quality
    • Non-production – hosting is paid for, but data is not of production quality

  8. Select your Authentication method. For details on supported authentication types, see the Authentication section below. Curators can also add or change authentication methods later.

  9. Select Done! to complete the registration.

Congratulations! Your service is registered in the Catalog.

The discoverable status of the service defaults to the value set by the Mendix Admin. For more details, see the Settings section of Catalog Administration.

Selecting an Authentication Method

Publishers of a service can determine how consuming developers will need to identify themselves when consuming the service.

The Catalog supports the following methods:

  • Basic authentication – Authenticate from a username and password
  • Active session – For Mendix services, authenticate from the open and active browser session
  • Mendix SSO – For Mendix services, authenticate from single sign-on using the Mendix SSO module
  • OAuth – Authenticate with OAuth
  • OpenID Connect – Authenticate with OpenID Connect, built on top of OAuth 2.0 and used with the OIDC SSO module
  • Other – Specify other ways to authenticate, including custom modules

Fill in as many details as you can to ensure that consuming developers can easily authenticate themselves to consume your service.

Selecting a Marketplace Module (Optional)

If you are using a module from the Mendix Marketplace, select Other and then choose the module in the Marketplace Module dropdown list.

Contract Structure

All ZIP contracts must include a primary document, named primary.

The other documents in the ZIP file should be structured within a series of nested folders, in which each segment of the URI path is represented by its own folder. It’s possible to use absolute URLs or relative URIs, but these have different top-level folders:

  • Absolute URL – The entire URL is represented in the folder structure, starting with an http or https folder in the root of the ZIP file. This top-level http or https folder contains a folder named after the domain. The domain folder contains a series of other folders and files representing the rest of the URL path.
  • Relative URI – The folders and files must be structured relative to the Document Base URL. In other words, relative URIs use a folder structure that matches the relative path as it is used in the primary document.

The following diagram shows examples of the ZIP contract structure for both URI types. The absolute folder structure is the same in each case, but the relative structure depends on the Document Base URL. Note that odata, v1, and docs are each separate folders, but in the absolute folder structure shown here, they are represented in a condensed format to save space.

Absolute and relative folder structures for two different base URLs.