REST requests

REST resources are available for solutions, entities, and aggregates. You can retrieve and manage resources by using the requests in the REST API. You can send GET requests in the address bar of a web browser. To access the REST interfaces securely, use an HTTPS connection.

Important: Modifying entities through REST can affect event processing. PUT and DELETE requests might fail on an entity that is being used by event processing. These requests can also cause the event processing to roll back.

Restriction: If an entity type inherits from a root entity type, a count request for both of these types returns the combined number of entities of the inherited type and the root type. If there is more than one inherited entity type, the count request includes all of the inherited entity types.

Table 1. REST requests
Request	Resource URI	Description
GET (parameters: group, max, regex)	http://`host`:`port`/ibm/ia/rest/solutions http://`host`:`port`/ibm/ia/rest/solutions/`solution_name`/entity-types/`entity_type`/entities http://`host`:`port`/ibm/ia/rest/solutions/`solution_name`/entity-types/`entity_type`/entities/`entity_id`/aggregate/`shared_aggregate_name` http://`host`:`port`/ibm/ia/rest/solutions/`solution_name`/aggregate/`global_aggregate_name` http://`host`:`port`/ibm/ia/rest/solutions/`solution_name`/entity-types/`entity_type`/count	Returns the content of the specified resource.
PUT	http://`host`:`port`/ibm/ia/rest/solutions/`solution_name`/entity-types/`entity_type`	Use the HTTP PUT method to pass the new entity data in the body of the request. Creates the specified entity if it does not exist; if the entity exists, it is modified with the new data. Send a PUT request to update fields or data in an entity or set of entities.
POST	http://`host`:`port`/ibm/ia/rest/solutions/`solution_name`/entity-types/`entity_type`	Use the HTTP POST method to pass the new entity data in the body of the request. The method succeeds only if the specified entity does not exist. If the object exists, the request fails with error code `409`. Use this method if you want to create a new entity but do not want to change existing entities.
DELETE (parameter: all-types)	http://`host`:`port`/ibm/ia/rest/solutions/`solution_name`/entity-types/`entity_type`	Use the HTTP DELETE method to specify the entity to delete in the body of the HTTP request.
DELETE	http://`host`:`port`/ibm/ia/rest/solutions/`solution_name`/state	Resets the state of a solution in a production environment. The state includes the rule agent history, solution recordings, cached engines, time triggers, pending events and global aggregates.

Parameters

Table 2. GET request parameters
Parameters	Purpose
group=`n`	Returns the entity list by pages. For example, `n=0` returns the first page, `n=1` returns the second page. See the max parameter to designate the page size. Full or partial pages are retrieved until an empty result is returned.
groupBy=`n`	Returns the value of a single shared aggregate, for a group of all the matching events for that aggregate. The shared characteristic by which events are grouped must be based on one of the following value types: integer, string, enumeration, absolute duration, year, month of year, day of week, day of month, hour of day, minute of hour, second of minute, time of day, or character. When you use the REST API directly with your own URL, you must encode the values.
max=`n`	Limits the number of items that are included in the returned entity list. `n` can be any integer more than 0. The default value is 50.
regex	Adds a regular expression query to the REST request so that only matching items are returned. This query is applied only to the Entity ID. Restriction: The regex parameter cannot be used to count or retrieve entities when entity offloading is enabled.
group=`n`&regex=`query`	You can combine the group and regex parameters. The regex query is applied after the entity list page is returned, which might reduce the number of returned items in the page.
when=`time`	For shared aggregates, you can include the when parameter to specify a ZonedDateTime value. If a value is specified, the call returns the value of the aggregate at that time instead of the current time. Use URL encoding in the `time` value. For example, instead of specifying `?when=2015-07-15T16:05:23.295+06:00`, you must specify `?when=2015-07-15T16:05:23.295%2B06:00`.
duration=`duration`	If you specify the when parameter, you can also specify the duration parameter to define a time period. The value of the property consists of a letter and number combination that designates a time unit as defined by the ISO 8601 specification: P (period): The first letter in the time value, for example, P30D is 30 days. Y (year): Time in years, for example, P1Y is one year. M (month): Time in months, for example, P6M is six months. D (day): Time in days, for example, P1D is 1 day. T (time): This letter indicates that the time includes hours, minutes, or seconds, for example, P1DT12H is one day plus 12 hours. H (hours): Time in hours, for example, PT36H is thirty six hours. M (minutes): Time in minutes, which must be preceded by the T designator, for example, PT6M is six minutes. S (seconds): Time in seconds, for example, PT30S is thirty seconds. Combined, the when and duration parameters define a time period that ends at the specified time. For example, in the following URI, the time period is from 5 a.m. on June 22 to 5 a.m. on June 24. `https://localhost:9443/ibm/ia/rest/solutions/MyCreditCardSolution/entity-types/creditcard.Account/entities/accountId1/aggregate/transnum?when=2015-06-24T05:00:00Z[GMT]&duration=P2D`

Table 3. DELETE request parameter
Parameter	Purpose
all-types=true	Deletes all entities in the solution. Do not use this parameter on a solution that is actively processing events. If the solution is processing events, a portion of the delete might not succeed and it might also cause the event processing to fail.

Tip: The intializeEntity(Entity) method is called when you create an entity by using the REST API POST or PUT method if the solution contains an EntityInitializer extension for the entity type or a parent of the entity type. The initializeEntity method can modify the attributes of the entity before creation, but if an error occurs, then the entity is not created.

Example of a GET request on a global aggregate resource

The following request returns the current value of the MaxDeposit global aggregate in the BankingSolution solution. You must include the defvar prefix in the name of the global aggregate:

http://localhost:9080/ibm/ia/rest/solutions/BankingSolution/aggregate/defvarMaxDeposit

Example of a GET request on a count resource

The following example of a GET request uses the count resource. It returns the number of com.test.Customer entities in BankingSolution solution.

https://localhost:9443/ibm/ia/rest/solutions/BankingSolution/entity-types/com.test.Customer/count

Examples of GET requests with the when and regex parameters

For query parameters in a web browser, append the parameter to the end of the URI request with a ? after the method call. For example:

https://host:port/ibm/ia/rest/solutions/solution_name/entity-types/entity_type/entities/entity_id?optional_parameter

Each query parameter is separated by &.

The following example GET request includes the optional regex parameter and returns a range of com.test.Customer entities that are in the BankingSolution solution:

https://localhost:9443/ibm/ia/rest/solutions/BankingSolution/entity-types/com.test.Customer/entities?regex=id[200-205]

The following example of a GET request uses the when parameter. It returns the value of the transnum shared aggregate at noon on June 30:

http://localhost:9080/ibm/ia/rest/solutions/MyCreditCardSolution/entity-types/creditcard.Account/entities/accountId1/aggregate/transnum?when=2015-06-30T12:00:00Z[EST]

Examples of GET requests with the groupby parameter

The following example of a GET request uses the groupBy parameter. It returns the value of the depositsByBank shared aggregate that is grouped by bank, which is a type of entity that is defined in the BankingSolution solution.

https://localhost:9443/ibm/ia/rest/solutions/BankingSolution/entity-types/Customer/entities/GoldCustomer/aggregate/depositsByBank?groupBy=Bank0735

The shared characteristic by which events are grouped must be based on one of the following value types: integer, string, enumeration, absolute duration, year, month of year, day of week, day of month, hour of day, minute of hour, second of minute, time of day, or character.

The following example of a GET request uses the groupBy parameter. It returns the value of the depositsByBank shared aggregate, which is defined as an integer:

https://localhost:9443/ibm/ia/rest/solutions/BankingSolution/entity-types/Customer/entities/GoldCustomer/aggregate/depositsByBank?groupBy=4

The following example of a GET request uses the groupBy parameter. It returns the value of the depositsByBank shared aggregate, which is defined as a string:

https://localhost:9443/ibm/ia/rest/solutions/BankingSolution/entity-types/Customer/entities/GoldCustomer/aggregate/depositsByBank?groupBy=hello

The following example of a GET request uses the groupBy parameter. It returns the value of the depositsByBank shared aggregate, which is defined as an enumeration. You must use the enumeration value that is spelled out as defined in the Business Model:

https://localhost:9443/ibm/ia/rest/solutions/BankingSolution/entity-types/Customer/entities/GoldCustomer/aggregate/depositsByBank?groupBy=alpha

The following example of a GET request uses the groupBy parameter. It returns the value of the depositsByBank shared aggregate, which is defined as an absolute duration. You must use ISO_8601 duration string to define the groupBy key:

https://localhost:9443/ibm/ia/rest/solutions/BankingSolution/entity-types/Customer/entities/GoldCustomer/aggregate/depositsByBank?groupBy=PT30M

The following example of a GET request uses the groupBy parameter. It returns the value of the depositsByBank shared aggregate, which is defined as a month of year. You must use an integer in the range 1-12 for each month, where 1 refers to January:

https://localhost:9443/ibm/ia/rest/solutions/BankingSolution/entity-types/Customer/entities/GoldCustomer/aggregate/depositsByBank?groupBy=3

The following example of a GET request uses the groupBy parameter. It returns the value of the depositsByBank shared aggregate, which is defined as a day of week. You must use the English word for the day (Monday, Tuesday) or use the number 1-7 where 1 is Monday:

https://localhost:9443/ibm/ia/rest/solutions/BankingSolution/entity-types/Customer/entities/GoldCustomer/aggregate/depositsByBank?groupBy=monday

The following example of a GET request uses the groupBy parameter. It returns the value of the depositsByBank shared aggregate, which is defined as a day of month:

https://localhost:9443/ibm/ia/rest/solutions/BankingSolution/entity-types/Customer/entities/GoldCustomer/aggregate/depositsByBank?groupBy=28

The following example of a GET request uses the groupBy parameter. It returns the value of the depositsByBank shared aggregate, which is defined as an hour of day:

https://localhost:9443/ibm/ia/rest/solutions/BankingSolution/entity-types/Customer/entities/GoldCustomer/aggregate/depositsByBank?groupBy=3

The following example of a GET request uses the groupBy parameter. It returns the value of the depositsByBank shared aggregate, which is defined as a minute of hour:

https://localhost:9443/ibm/ia/rest/solutions/BankingSolution/entity-types/Customer/entities/GoldCustomer/aggregate/depositsByBank?groupBy=59

The following example of a GET request uses the groupBy parameter. It returns the value of the depositsByBank shared aggregate, which is defined as a second of minute.

https://localhost:9443/ibm/ia/rest/solutions/BankingSolution/entity-types/Customer/entities/GoldCustomer/aggregate/depositsByBank?groupBy=59

The following example of a GET request uses the groupBy parameter. It returns the value of the depositsByBank shared aggregate, which is defined as a time of day. You must define the groupBy key as hh:mm:ss:

https://localhost:9443/ibm/ia/rest/solutions/BankingSolution/entity-types/Customer/entities/GoldCustomer/aggregate/depositsByBank?groupBy=04%3A24%3A50

The following example of a GET request uses the groupBy parameter. It returns the value of the depositsByBank shared aggregate, which is defined as a character:

https://localhost:9443/ibm/ia/rest/solutions/BankingSolution/entity-types/Customer/entities/GoldCustomer/aggregate/depositsByBank?groupBy=x

Examples of DELETE requests

The DELETE request with the all-types=true parameter removes entities of all types from a solution. For example:

https://localhost:9443/ibm/ia/rest/solutions/BankingSolution/entity-types?all-types=true

The DELETE state request clears and resets the state of a solution. The state includes rule agent history, cached engines, time triggers, pending events and global aggregates. For example:

https://localhost:9443/ibm/ia/rest/solutions/BankingSolution/state