The Admin SDK (ADK)

Overview

The Admin SDK is designed to provide access to the Management Repository API. It is an OpenAPI driven API, based on the MR OpenAPI file that can be located here

The API is broken up into a number of services representing different facets of the Management Repository, e.g. Portfolios, Applications, Environments, Features, Service Accounts, Authentication and so forth.

Installing the ADK in your project

We currently have Java 8 and Java 11 ADKs released. Typescript and DotNet ADKs will follow soon.

Maven - Java 8
<dependency>
  <groupId>io.featurehub.mr.sdk</groupId>
  <artifactId>java8-admin-client</artifactId>
  <version>[1.1, 2)</version>
</dependency>
Maven - Java 11
<dependency>
  <groupId>io.featurehub.mr.sdk</groupId>
  <artifactId>java11-admin-client</artifactId>
  <version>[1.1, 2)</version>
</dependency>
Gradle - Java 8
implementation 'io.featurehub.mr.sdk:java8-admin-client:[1.1,2)'
Gradle - Java 11
implementation 'io.featurehub.mr.sdk:java11-admin-client:[1.1,2)'

Using the ADK

As we release new Admin tool kits, we will add code examples in different languages.

for Java, because it doesn’t have optional parameters, all parameters must be specified, even if null.
when in doubt, the OpenAPI document is the source of truth and this document can become out of date.

Creating the API Client to enable you to talk to the server

In all ADKs, there is an API client that you need to specify where the server is located.

Java 8
import io.featurehub.admin.ApiClient;
import io.featurehub.admin.Configuration;

ApiClient api = new ApiClient();
// wherever your host is located
api.setBasePath("http://localhost:8085");

// if you are running a single authenticated client, you can now do this:
Configuration.setDefaultApiClient(api);
// and you won't have to pass the api around
Java 11
import io.featurehub.admin.ApiClient;

ApiClient api = new ApiClient();
// wherever your host is located
api.setHost("localhost").setPort(8085)
// if you are running a single authenticated client, you can now do this:
Configuration.setDefaultApiClient(api);
// and you won't have to pass the api around
If you do not set the global default API client, then you will have to keep track of the client and pass it as the parameter when you construct the various apis. E.g. new AuthServiceApi() becomes new AuthServiceApi(api)

Authentication

Once the Api client is created, you need to provide a "Bearer Token" (access token) to authenticate it. Access token can be obtained via FeatureHub Admin Console on the "Admin Service Account" Page (only accessible by super admins). Make sure Admin Service Account has enough access rights to perform ADK operations that you are planning to do. More on Admin Service Accounts here

Java
// create the Auth Service
AuthServiceApi authApi = new AuthServiceApi();

The differences between 8 and 11 are in how to specify the token to the APIClient.

Java 8
String token = "your_token"
api.setBearerToken(token)
Java 11
// tell the API that it should add the bearer token onto the outgoing requests
api.setRequestInterceptor(builder -> {
builder.header("Authorization", "Bearer " + token)
} );

Once authenticated, you can now use the SDK and there are no differences between Java 8 and 11.

APIs

Managing Portfolios

This operation lets you, presuming authenticated user has permission, manage Portfolios. The core functionality is in PortfolioServiceApi. Always examine the generated code for details on what error codes and status codes can be returned.

A portfolio consists of Applications and Groups entities. Once you have a portfolio, you can perform operations on those entities.

Java
PortfolioServiceApi portfolioService = new PortfolioServiceApi();

Create Portfolio

This operation creates a portfolio, and indicates whether you want to return any created groups and applications inside the portfolio. Currently the API does not allow you to create groups and applications when creating portfolios.

Java Definition
Portfolio createPortfolio(Portfolio portfolio, Boolean includeGroups, Boolean includeApplications)
Java use
Portfolio portfolio = portfolioService.createPortfolio(new Portfolio().name("name").description("description"), null, null)

Delete Portfolio

This operation will delete the portfolio and everything inside it. This is a final operation so be careful with it. It returns true if successful, false if not.

Java Definition
Boolean deletePortfolio(UUID id, Boolean includeGroups, Boolean includeApplications, Boolean includeEnvironments)
Java use
Portfolio portfolio = portfolioService.createPortfolio(id, null, null, null)

Searching for Portfolios

This operation allows to search through portfolios by name

Java Definition
List<Portfolio> findPortfolios(Boolean includeGroups, Boolean includeApplications, SortOrder order, String filter, String parentPortfolioId)
Java use
List<Portfolio> portfolios = portfolioService.findPortfolios(true, true, SortOrder.ASC, null, null)

  • includeGroups: if true, will fill in the groups available to each portfolio

  • includeApplications: if true, will fill in the applications available to each portfolio

  • order: if null, then whatever order they are in the database, otherwise specify ascending or descending

  • filter: a partial string to search for - it operates like a database like. All comparisons are case insignificant.

  • parentPortfolioId: obsolete

This will return all portfolios in ascending order.

Get a Portfolio

This operation allows to get the details of a portfolio by ID.

Java Definition
Portfolio getPortfolio(UUID id, Boolean includeGroups, Boolean includeApplications, Boolean includeEnvironments)
Java use
Portfolio portfolio = portfolioService.getPortfolio(id, true, true, true)

  • id: the portfolio’s id

  • includeGroups: if true, will fill in the groups available to each portfolio

  • includeApplications: if true, will fill in the applications available to each portfolio

  • includeEnvironments: if true, all applications will have their environments listed

This would get the portfolio and all of its groups, applications and within those applications, their environments.

Update a Portfolio

This operation allows to update a portfolio’s name and description.

Java Definition
Portfolio updatePortfolio(UUID id, Portfolio portfolio, Boolean includeGroups, Boolean includeApplications, Boolean includeEnvironments)
Java use
Portfolio portfolio = portfolioService.updatePortfolio(id, new Portfolio().name("newName").description("new description"), true, true, true)

  • id: the portfolio’s id

  • portfolio: the updated portfolio details.

  • includeGroups: if true, will fill in the groups available to each portfolio

  • includeApplications: if true, will fill in the applications available to each portfolio

  • includeEnvironments: if true, all applications will have their environments listed

Managing Applications

Managing Groups

Managing Environments

Managing Features

This series of APIs allows you to create features. Features exist at the application level, so once they have been created, they will exist in all environments.

Features once deleted don’t actually go away, they are archived and their key is changed so you can recreate a new feature with the same key, but you won’t lose their audit history.

Java use
FeatureServiceApi featureService = new FeatureServiceApi();

Creating a new feature

Java Definition
List<Feature> createFeaturesForApplication(UUID id, Feature feature)
Java use
List<Feature> allFeatures = featureService.createFeaturesForApplication(appId,
   new Feature().name("Feature's Name").key("FEATURE_KEY").valueType(FeatureValueType.BOOLEAN))

Required fields are:

  • name - the name given to the feature as it will appear in the admin console

  • key - the key, unique among the applications

  • valueType - the type of the feature: boolean (flag), number, string or json

Managing Feature Values

Feature Values exist on a specific feature in a specific environment. Flag features must have a value (true or false), whereas all other feature types (String, Number, Json) can have feature value set as null. All feature values must also have "locked" property set to true or false.

Java use
EnvironmentFeatureServiceApi featureValueService = new EnvironmentFeatureServiceApi();

OpenAPI Files

If you use a language we don’t provide an artifact for or use an OpenAPI generator that is different from the one we are using, the information on the latest API is located at: https://github.com/featurehub-io/featurehub/tree/main/infra/api-bucket/files/mrapi

Or can be served from: http://api.dev.featurehub.io/mrapi/1.1.5.yaml