On this page:

Server

URI Templates

HTTP ActionMedia TypeURI TemplatesDescription
GETapplication/jsonserverInformation about REST API internal state

JSON Representation

PropertiesDescriptiontypeOccurs
hrefAuto referenceURI1
name"Server"String1
startDateStarting date of the serverDate1
memoryStatistics about memory usage (mega-bytes)Structure
memory.totalInitialMemoryTotal memory according to the JVM in mega-bytes, before initializing memory cacheInteger1
memory.totalMemoryTotal memory according to the JVM in mega-bytesInteger1
memory.freeMemoryFree memory according to the JVM in mega-bytesInteger1
memory.usedMemoryTotal memory - Free memoryInteger1
requestsStatistics about requestsStructure1
requests.totalCounterTotal number of requestsInteger1
requests.errorsCounterTotal number of requests in errorsInteger1
requests.totalTimeTotal elapsed time of requests millisecondsInteger1
requests.averageTimeTotal elapsed time of requests in millisecondsInteger1
requests.maxTimeLongest elapsed time of all requests in millisecondsInteger1
clientsStatistics about concurrent clientsStructure1
currentConcurrentClientsThe current number of concurrent clients in read time.
Note that  the current request to fetch this information is not included in the count.
Integer1
maxConcurrentClientsThe maximum number of concurrent clientsInteger1
statusServer status either "LOADING" or "READY"String

1

loadDate

Date of Memory cache update. This date is set at start time of

the server or when a reload is requested.

Date1
abortedDomainsArray of aborted domains. An aborted domain is a domain for which loading has failed.Array1
abortedDomains[]An aborted domainStructure0..1
abortedDomains[].nameDomain nameString1
abortedDomains[].loadingDateDate of loading start when the loading has been failedString1
license.status

License status regarding access to Central Bases

Use CaseStatusDescription
No LicenseNO_LICENSE_KEYLicense key was not found
INVALID_LICENSE_KEYLicense key is not valid
CANNOT_ACCESS_LICENSE_KEYLicense key file is not readable
INVALID_LICENSE_FILECannot find license key file
Restricted LicenseRESTRICTED_LICENSELicense is a restricted license
GLOBAL_ACCESS_TOKENS_EXCEEDED

License is a restricted license,
and quota of global access tokens is exceeded

UNIT_ACCESS_TOKENS_EXCEEDEDLicense is a restricted license,
and quota of unit access tokens is exceeded
Unrestricted LicenseUNRESTRICTED_LICENSELicense is an unrestricted license
String1
domainsLocationsGet data source name and schema name for each domain. The ADMINISTRATOR role is required.Structure0..1
recommendedDbVersionThe preferred version of AIP (for compliancy with database schema)

securityMode

This is the configuration value of property security.mode from the security.properties file:

  • "default": authentication based of configuration files
  • "ldap": authentication base on LDAP protocol
  • "saml": authentication based on SAML protocol
String1
samlSingleLogout

This is the configuration value of security.saml.single.logout property from security.properties file.

  • "true": logout action is enabled for "saml" security mode
  • "false": logout action is disabled for "saml" security mode
Boolean1
languagesInstalled translationsArray1
languages[ ]An available locale languageString0..1
reportEnabledCheck whether the configuration variable report. is set report.reportGeneratorBoolean1


JSON Example

GET DEMO
{
	"href": "server",
	"name": "Server",
	"startDate": {
		"time": 1612255923923,
		"isoDate": "2021-02-02"
	},
	"memory": {
		"totalInitialMemory": 109,
		"totalMemory": 125,
		"freeMemory": 44,
		"usedMemory": 81
	},
	"requests": {
		"totalCounter": 20,
		"errorsCounter": 0,
		"totalTime": 18447419617,
		"averageTime": 922370980,
		"maxTime": 929175903
	},
	"clients": {
		"currentConcurrentClients": 0,
		"maxConcurrentClients": 1
	},
	"loadDate": {
		"time": 1612256578092,
		"isoDate": "2021-02-02"
	},
	"abortedDomains": [],
	"status": "READY",
	"version": "X.X.X-XXX",
	"recommendedDbVersion": "8.3.3",
	"license": {
		"status": "NO_LICENSE_KEY"
	},
	"securityMode": "default",
	"samlSingleLogout": false,
	"sessionTimeout": 900,
	"languages": [
		".gitkeep"
	],
	"reportEnabled": false,
	"jiraEnabled": true,
	"domainsBinding": {
		"href": "server/domains-bindings",
		"name": "Domains/schemas bindings"
	},
	"authorizations": {
		"href": "server/authorizations",
		"name": "Authorized applications definitions per users"
	}
}
}


Server Cache Management

Warning

Administrator role is required.

REST server stores portfolio objects, configuration, and snapshots in a memory cache. This memory cache is loaded as soon as the REST Server is started.

An URL allows to reload all domains in memory cache. This action may be required when a new snapshot has been added, and can be performed from a command line with a tool such as "curl":


Use Curl for automation:
C:> curl -u admin:cast -H "Accept: application/json" http: //localhost:9999/testContext/rest/server/reload


For each domain, and for each application an Index file is created for Lucene library. This index allows to search for a components. Lucene index files are created at start time and reload time if this option is enabled:

<context-param>
    <param-name>rebuildComponentsSearchIndexesOnStart</param-name>
    <param-value>true</param-value>
</context-param>

URI Templates

HTTP ActionMedia TypeURI TemplatesDescription
GETapplication/jsonserver/reload{?parameters}

Sync clients with new domains.

Reload the domains configuration and refresh the server memory cache,
Example of use: A new application onboarding requires to create a new ED domain in the domains.properties file.

The client may receive an HTTP Status 503 "Service not available" if a server/refresh call is already in progress.

In case of intensive traffic, the service awaits for the end of current processing request to start.

This web service has the following effects

  • Reload the configuration of domains (domains.properties file)
  • Reload the server memory cache
  • Rebuild Lucene Indexes
  • Respond a “503 Service unavailable“ to any client during the reload
  • Invalidate the browser cache
  • Reset the cache of user authorizations


GETapplication/jsonserver/refresh{?parameters}

Sync clients with new snapshots.

Refresh the server memory cache when a new snapshot has been added.
Example of Usage:  A new snapshot has been taken for an ED domain.
Example of Usage: AAD domains needs to be refreshed when a new application or a new snapshot has been added.

This processing is made in the background with no interruption for HD clients, and reduced interruption for ED clients.

This web service has the following effects

  • Reload the server memory cache
  • Rebuild Lucene Indexes
  • Respond a "503 Service unavailable to ED clients requesting Lucene index data, whereas this Lucene index is under construction for this specific domain.
  • Invalidate the browser cache
  • Reset the cache of user authorizations

Note: If two concurrent requests are sent for 2 different domains, then these domains will be refreshed in parallel.

Note: onboarding of a new applications must be performed with the "server/reload" or the "server/domains-bindings" web service that will update the domains.properties configuration file and will trigger a "server/reload" service for these domains.


GETapplication/jsonserver/reset

Sync clients with new authorizations.

Invalidate the browser cache and reset the cache of user authorizations.

Example of usage: You want to take into account the changes of the authorizations file , without awaiting for the next login.

Parameters

URI Parameter

Description

Values

Default value

domainSpecify a single domain to reload (for example to refresh a domain after a snapshot)a string$all

DBMS Warm-up Service

Warning

Administrator role is required.

This service fetches data (results, components, violations) for domains hosted in central bases, in order to pre load data in memory afer a DBMS cold restart.

It avoids to penalize first user fetching data.

This service loops on each domain hosted by a central base, and trigger some queries on components, violations and assessment results.


Use Curl for automation:
C:> curl -u admin:cast  http: //localhost:9999/testContext/rest/server/warmup

URI Templates

HTTP ActionMedia TypeURI TemplatesDescription
GETapplication/jsonserver/warmupWarm up DBMS after a cold restart (central base hosts only)


Lucene Index File

For each domain, and for each application an Index file is created for Lucene library. This index allows to search for a components.

URI Templates

HTTP ActionMedia TypeURI TemplatesDescription
PUTapplication/json{Domain}/components-index

Create or overwrite the components search index for a domain

Warning

Administrator role is required.

GETapplication/json{Domain}/components-indexGet index status for a domain


JSON Representation

PropertiesDescriptiontypeOccurs
hrefAuto referenceURI1
nameNameString1
status
  • upToDate : Index is up to date
  • N/A : not applicable, no index
  • toUpdate : last snapshot is more recent than the index date, an index rebuild is required
String1
dateIndex file dateDate0..1
lastSnapshotDateLast Snapshot dateDate0..1
sizeIndex file sizeInteger0..1

JSON Example

{
	"href": "ENDTOEND83/components-index",
	"name": "Components search index for applications of ENDTOEND83",
	"status": "upToDate",
	"date": {
		"time": 1496752452859,
		"isoDate": "2017-06-06"
	},
	"lastSnapshotDate": {
		"time": 1493778823000,
		"isoDate": "2017-05-03"
	},
	"size": 4145870
}


Domains Bindings

A Domain binding associates a domain name with a data source name and a schema name.

This resource is based on the use of domains.properties file.

URI Templates

HTTP ActionMedia TypeURI TemplatesDescription
GETapplication/jsonserver/domains-bindings

Get all domains bindings

Warning

Administrator role is required.

PUTapplication/jsonserver/domains-bindings

Update the domains bindings, or create new domains bindings.

A triplet (domain, data source, central) is replaced for an existing domain or an existing central, otherwise it is added.

This web service triggers the "reload" service for the domains listed in the payload, in order to update the server memory cache and Lucene index files.

This Web service overwrites the domains.properties file.

Warning

This service accepts the "Authorization" HTTP header to transmit user's credentials, so that a prior call to the login "service" is not required. Thus, we can start the Web Server with an empty list of domains, and bypass the "login" service that prevents connection when no domain is defined.

In case of exception when writing this file, an HTTP Status "403 Forbidden" is returned. Check the permissions of this file.

Warning

Administrator role is required.

Example:

Assuming there are two existing domains AED1, AED2, add a new domain:

[
	{
		"name": "AED3",
		"dataSource": "DEV_CSS2",
		"schema": "appli1_central"
	}
]

Assuming there are three existing domains AED1, AED2, AED3, change schemas for domains AED1, AED2:

[
	{
		"name": "AED1",
		"dataSource": "DEV_CSS2",
		"schema": "appliA_central"
	},
	{
		"name": "AED2",
		"dataSource": "DEV_CSS2",
		"schema": "appliB_central"
	}
]
DELETEapplication/jsonserver/domains-bindings

Update the database binding for a list of domains, or create some new domains with their own bindings.

This web service does not need to trigger the "reload".

This Web service overwrites the domains.properties file.

Warning

This service accepts the "Authorization" HTTP header to transmit user's credentials, so that a prior call to the login "service" is not required. Thus, we can start the Web Server with an empty list of domains, and bypass the "login" service that prevents connection when no domain is defined.

In case of exception when writing this file, an HTTP Status "403 Forbidden" is returned. Check the permissions of this file.

Warning

Administrator role is required.

Example:

Assuming there are two existing domains AED1, AED2, remove domain AED2

[
	{
		"name": "AED2"
	}
]

JSON Representation

PropertiesDescriptiontypeOccurs
nameDomain nameString1
dataSourceData source nameString1
schema

Schema Name

String1

JSON Example

[
	{
		"name": "AED1",
		"dataSource": "DEV_CSS2",
		"schema": "appli1_central"
	},
	{
		"name": "AED2",
		"dataSource": "DEV_CSS2",
		"schema": "appli2_central"
	}
]

Authorizations

This resource is based on the use of authorizations.xml file.

URI Templates

HTTP ActionMedia TypeURI TemplatesDescription
GETapplication/jsonserver/authorizations

Get all users' authorizations

Warning

Administrator role is required.

PUTapplication/jsonserver/authorizations

Update users' authorizations. Create or replace authorizations

This Web service overwrites the authorizations.xml file.

Warning

Administrator role is required.

If you set an empty list of authorizations, then authorizations are removed.


JSON Representation

PropertiesDescriptiontypeOccurs
useruse name.Excludes the group property
String1
groupLDAP group name. Excludes the user property.String1
authorizationsAll authorizations for a userArray0..1
authorizations[ ]

An authorization defines which applications can be accessed

Structure1
authorizations[ ].allApplicationsSet applications access to all applicationsBoolean0..1

authorizations[ ].application
authorizations[ ].adgDatabase

Allow access to an application matching application name and adgDatabase name;String0..1
authorizations[ ].applicationPattern
authorizations[ ].adgDatabasePattern
Allow access to all applications matching applicationPattern regular expression and adgDatabasePatern regular expressionString0...1

authorizations[ ].tag
authorizations[ ].category
authorizations[ ].restrictions

Allow access to all applications matching a tag of a categoryString0..1
authorizations[ ].technology
authorizations[ ].restrictions
Allow access to all applications matching a technologyString0..1
authorizations[ ].restrictionsAll restrictions, applicable for authorizations defined with tag, category and technology attributesArray0..1
authorizations[ ].restrictions[ ]A restrictionStructure0..1

authorizations[ ].restrictions[ ].application
authorizations[ ].restrictions[ ].adgDatabase

Deny access to an application matching application name and adgDatabase nameString0..1
authorizations[ ].restrictions[ ].applicationPattern
authorizations[ ].restrictions[ ].adgDatabasePattern
Deny access to all applications matching applicationPattern regular expression and adgDatabasePatern regular expressionString0...1
authorizations[ ].restrictions[ ].tag
authorizations[ ].restrictions[ ].category
Deny access to all applications matching a tag of a categoryString0..1
authorizations[ ].restrictions[ ].technologyDeny access to all applications matching a technologyString0..1

JSON Example

[
	{
		"user": "John",
		"authorizations": [
			{ "application": "app1",	"adgDatabase": "app1_central" },
			{ "application": "app2",	"adgDatabase": "app2_central" }
		],
	},
	{
		"user": "Admin",
		"authorizations": [	{"allApplications": true } ]
	},
	{
		"user": "Jimmy",
		"authorizations": [
			{ "technology": "JEE",
  		      "restrictions": [  {  "application": "appli2", "adgDatabase": "appli2_central" } ]
            }
		]
	}
]