REST requests

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.

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`	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. 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.
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.
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.

Examples

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]

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