Rulestore API

From RuleML Wiki
Jump to: navigation, search

RESTful APIs are well supported and understood by a large community of Web developers. Wide scale rule-based reasoning on the Web requires rules to be exposed as Linked Data objects and in a manner suitable for most of the Web developers. While designing rules and rulesets is still an expert-guided task, exposing rules as Linked Data will greatly improve their usage in Web reasoning.

As RuleML is a unifying family of XML-serialized rule languages spanning across all industrially relevant kinds of Web rules, it is useful to provide RuleML rules as Linked Data[1] objects to bridge the gap between Linked Data and Rules. This specification aims to fill that gap by defining an easy-to-use and easy-to-deploy a REST API[2] layer that can act as a proxy for any XML Database. The Rulestore API should support:

  • Easy-to-process representations of resources (JSON[3], XML[4])
  • Easy-to-construct lists of resources based on various selection criteria

The first version API layer should provide the basic functionality, while future versions may provide a range of configuration options to support additional, domain-specific customization and functionality.

As the Rulestore API is intended to be used with various kinds of rules it does not provide functionality to update rule constituents[5] such as events, conditions, conclusion, or action. Therefore a rulestore implementation will allow only destructive updates, i.e., a rule is updated by deleting and replace it with a new rule.

Related work includes the earlier Java-oriented API[6] and the emerging OMG 'meta'-API[7].


Contents

1 Resources

The API Data Model

A rulestore is a knowledge base for the storage and retrieval of rules and rulesets. Basically, a rulestore contains 0..* repositories. Each repository contains a collection of rulesets and one collection of rules.

The API resources ( repositories, rules and rulesets) are identified by URIs.

1.1 Repositories

The Repository Data Model

A repository is an application-defined container. Rules and rulesets are first class citizens of repositories. A repository may be empty (no rules, no rulesets). An application can retrieve/create/update/delete new artifacts (rulesets, rules), or add/remove rules to/from rulesets. Notice that rules are not REST sub-resources of rulesets.

1.2 Rulesets

The Ruleset Data Model

A ruleset is a collection of RuleML rules typically designed to satisfy a specific goal.

Rulesets are managed as resources of repositories. A ruleset may belong to many repositories (shared ruleset) or to exactly one repository (private ruleset). A client can retrieve a ruleset and add/remove rules to/from a ruleset.

1.3 Rules

The Rule Data Model

The API does not handle the rule constituents such as event, condition, conclusion and action.

The process of create/delete of rule constituents is handled by the API clients. This depends on how the clients use the rules (e.g., consuming, RuleML, JSON Rules or other).

The rulestore reference implementation uses RuleML rules in their XML representation (see also the API related XML responses).

2 API Requests

The following principles are considered when authoring resources:

  • GET is used to retrieve a representation of a known resource.
  • POST is used to create a new, dynamically named, resource. When a client submits a representation of a resource then the server creates an URI of that resource and returns a specific HTTP status code[8][9] and and the resource URI as value of an appropriate HTTP header[8][10] Accept-Language.
  • PUT is used to edit/update a known resource and it is NOT used for resource creation.
  • DELETE is used to remove a known resource.


The HTTP Accept header may be sent to specify the response type.

  • Accept:application/json should be used to specify that a JSON response is desired.
  • Accept:application/xml should be used to specify that an XML response is desired.
  • Accept:text/prolog may be used to specify that a Prolog response is desired.

3 API Responses

The API allows any data representation language as language host for responses including JSON-encoded[11] responses as well for XML-based ones (native RuleML).


The HTTP request header - "Acceptable languages for response", must be used to receive responses in specific languages. The API will return a corresponding Content-Language to specify the response language.


The HTTP response header Content-Type indicates the MIME type of the response.

3.1 JSON Response

The JSON responses follow the traditional REST responses. The client is responsible for parsing and interpreting the response. Error responses will be indicated only by sending the appropriate HTTP status codes. The response content type is application/json.

3.2 XML Response

Similar to JSON-based responses, the XML responses are parsed and interpreted by the clients. However, in the case of XML responses the API may provide an XML Schema as a semantic reference. Error responses will be indicated only by sending the appropriate HTTP status codes. The response content type is application/xml.


3.3 RDF Responses

When the request uses Accept: application/xml+rdf then a RDF/XML representation is requested. To request an N-Triples representation the client must include in the HTTP header Accept: text/plain while other RDF representations such as Turtle require Accept: text/turtle.

3.4 Other Responses

Custom responses may be sent by the API assuming existing converters from/to RuleML and the response language. Specific content types must be sent/received.


For example if the client requests Prolog rules by sending HTTP header Accept:text/prolog then the API should answer with a Content-Language: text/prolog.If a converter RuleML2Prolog does not exist then the HTTP 501 Not Implemented must be submitted.

3.5 Example - Requesting an XML Representation

The client requests:

GET /rulestore/teststore/repositories/adrian/rules/r101  HTTP/1.1
Host: ruleml.org
Accept: application/xml
Accept-Language: en

The server must answer with an XML representation of the resource (if available) or with a HTTP response error if not available. The response header would be:

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Language: en

and the response body contain the XML representation of the requested resource such as:

  <Implies xml:id="r101" node="http://ruleml.org/rulestore/teststore/repositories/adrian/rules/r101">
  <ns:name>
    <en> My rule name </en>
  </ns:name>
  <ns:description>
    My rule text description
  </ns:description>
  <meta>structured metadata</meta>
  <on>
   my event expression
  </on>
  <if>
    my condition formula
  </if>
  <then>
   my conclusion/action formula
  </then>
 </Implies>

4 Database support

The API does not request a specific database support. The reference implementation intends to use the IBM DB2 XML database.


5 Datatypes

The Linked Data Platform 1.0, W3C Working Draft requires Linked Data platform containers to deliver resource representations using the following dataytpes:

 http://www.w3.org/2001/XMLSchema#boolean	        Boolean type as specified by XSD Boolean
 http://www.w3.org/2001/XMLSchema#date	                Date type as specified by XSD date
 http://www.w3.org/2001/XMLSchema#dateTime	        Date and Time type as specified by XSD dateTime
 http://www.w3.org/2001/XMLSchema#decimal	        Decimal number type as specified by XSD Decimal
 http://www.w3.org/2001/XMLSchema#double	        Double floating-point number type as specified by XSD Double
 http://www.w3.org/2001/XMLSchema#float	                Floating-point number type as specified by XSD Float
 http://www.w3.org/2001/XMLSchema#integer	        Integer number type as specified by XSD Integer
 http://www.w3.org/2001/XMLSchema#string	        String type as specified by XSD String
 http://www.w3.org/1999/02/22-rdf-syntax-ns#XMLLiteral	Literal XML value as specified by RDF

I appears that XML Schema Datatypes[12] are preferred and possibly other datatypes would be considered.

6 URI Design Principles

According with Linked Data principles[13], Uniform Resource Identifiers[14][15][16] (URI), more formally HTTP URIs (URI using the HTTP scheme) are used to denote our resources.

7 List of API requests

The URIs described in the below Table omit the t=[token] the authentication code necessary to access resources. A general specification may consider various kinds of tokens, e.g., different for retrieval and resource creation and so on. The necessary list of tokens is part of the definition of an access policy to the rulestore.

Another parameter, l=[language] can be added to retrieve a resource using a specific language. If such a language does not exist, then the default language (en) is delivered.

Action Repository/Rule/Ruleset
Retrieve all
   GET /[store_id]/repositories
   GET /[store_id]/repositories/[repository_id]/rules/
   GET /[store_id]/repositories/[repository_id]/rulesets
Retrieve by ID
   GET /[store_id]/repositories/[repository_id]
   GET /[store_id]/repositories/[repository_id]/rules/[rule_id]
   GET /[store_id]/repositories/[repository_id]/rulesets/[ruleset_id]
Retrieve by name
   GET /[store_id]/repositories/name/[name]
   GET /[store_id]/repositories/[repository_id]/rules/name/[name]
   GET /[store_id]/repositories/[repository_id]/rulesets/name/[name]
 
Search
   GET /[store_id]/repositories/search/[search_string]
   GET /[store_id]/repositories/[repository_id]/rules/search/[search_string]   
   GET /[store_id]/repositories/[repository_id]/rulesets/search/[search_string]
 
Create
   POST /[store_id]/repositories
   POST /[store_id]/repositories/[repository_id]/rules
   POST /[store_id]/repositories/[repository_id]/rulesets
Edit
   PUT /[store_id]/repository/[repository_id]/rulesets/[ruleset_id]/rules/[rule_id]
Delete
   DELETE /[store_id]/repositories/[repository_id]
   DELETE /[store_id]/repositories/[repository_id]/rules/[rule_id]
   DELETE /[store_id]/repositories/[repository_id]/rulesets/[ruleset_id]
   DELETE /[store_id]/repositories/[repository_id]/rulesets/[ruleset_id]/rules/[rule_id]


7.1 List of all URL parameters

  • [token]:Text: is the necessary access token that is typically obtained by a client registering the API.
  • [repository_id]:Text: is a global ID in the scope of all rule repositories defined by a [store_id]:TExt deployment.
  • [name]:Text: has the same meaning as name from Schema.org vocabulary. Name is not unique in any scope.
  • [description]:Text: Text has the same meaning as description from Schema.org vocabulary.
  • [ruleset_id]:Text is a global ID in the scope of all rulesets
  • [rule_id]:Text is a global ID in the scope of all rulesets
  • [search_string]:Text: is a usual search string
  • [language]<code>:Language is a language code. It can be present on any request and defines the language the user prefers. If <code>[name] and/or [description] of a specific ruleset/rule is available in this language, then ruleset/rule the will be returned using this language, otherwise English is the default.

8 Retrieving Resources

  • As a general principle, when only one resource is retrieved, then a resource representation (JSON object) is sent as the service answer, together with HTTP status code HTTP 200 OK.
  • To list the resource members of a collection (such as the ruleset), the client sends a GET request to the URI of the collection (e.g., ruleset). The returned document must contain at least the URIs of the member resources (e.g, rules). The response may

describe all, or only a partial list, of the member resources in that collection ( See resource pagination ).

  • If many resources come into the result set, then the service answer is a collection (JSON array) containing the URIs of the collection members ( See also resource pagination ).


Errors:

  • When a resource is not available, then the service answers a HTTP 404 Not Found.
  • When the request URL has wrong parameters or is ill-formed, then the service will return an HTTP 400 Bad Request status.
  • When a resource is requested using an HTTP method different from the necessary one, then the service will return an HTTP 405 Method Not Allowed
  • The precedence of errors is 405/404 405/400
  • More on HTTP status codes.


8.1 Retrieving repositories

8.1.1 Get all repositories

Retrieve an array representation of the repositories

GET /[store_id]/repositories?t=[token]
8.1.1.1 Response
  • An array representation of all repositories
 { 
  "id": "[store_id]",
  "name": "[name]",
  "description": "[description]",
  "metadata": {[metadata]},
  "repositories": [
          "[repository_id1]", ..., "[repository_idN]"
          ]
 }

Errors:

  • If the store does not contain any repository, then HTTP 404 Not Found.
  • Wrong URL (invalid parameters): 400 Bad Request


8.1.2 Get repository by ID

Retrieve a representation of the repository identified by [repository_id].

GET /[store_id]/repositories/[repository_id]/?t=[token]
8.1.2.1 Response
  • A representation of the repository
 { 
  "id":"[repository_id]", 
  "name": "[name]",
  "description":"[description]", 
  "metadata":{[metadata]},
  "rules": [
          {
           "id": "[rule_id1]",
           "name": 
                  {
                   "en": "[rule_name1]",
                    "[language]": "[rule_name1]"
                  }
           },
            ..., 
           {
            "id": "[rule_idN]",
            "name": 
                   {
                    "en": "[rule_nameN]",
                    "[language]": "[rule_nameN]"
                   }
            }
           ],
   "rulesets": [
              {
                 "id": "[ruleset_id1]",
                 "name": {
                          "en": "[ruleset_name1]",
                          "[language]": "[ruleset_name1]"
                          }
                    },
                    ..., 
              {
                "id": "[ruleset_idN]",
                "name": {
                            "en": "[ruleset_nameN]",
                             "[language]": "[ruleset_nameN]"
                          }
               }
              ]           
 }

Errors:

  • If the store does not contain such a repository, then HTTP 404 Not Found
  • Wrong URL (invalid parameters): HTTP 400 Bad Request


8.1.3 Get repositories by name

Retrieve an array representation of all repositories with the same [name].

GET /[store_id]/repositories/name/[name]?t=[token]
8.1.3.1 Response
  • An array representation of all repositories with the same [name] from this store
 { 
  "id": "[store_id]",
  "name": "[name]",
  "description": "[description]",
  "metadata": {[metadata]},
  "repositories": [
                    "[repository_id1]", ..., 
                  ]
 }

Errors:

  • If the store does not contain any repositories with this [name], then HTTP 404 Not Found.
  • Wrong URL (invalid parameters): HTTP 400 Bad Request.

8.2 Retrieving rulesets from a repository

8.2.1 Get all rulesets

Retrieve an array representation of the

GET /[store_id]/repositories/[repository_id]/rulesets?t=[token]
8.2.1.1 Response
  • An array representation of all rulesets from this rule repository
 { 
    "id":"[repository_id]", 
    "name":"[name]",
    "description":"[description]", 
    "metadata":{[metadata]},
    "rulesets": [
               {
                 "id": "[ruleset_id1]",
                  "name": {
                           "en": "[ruleset_name1]",
                           "[language]": "[ruleset_name1]"
                           }
                },
                ..., 
                {
                   "id": "[ruleset_idN]",
                   "name": {
                              "en": "[ruleset_nameN]",
                               "[language]": "[ruleset_nameN]"
                            }
                 }
                ]
  }

Errors:

  • If the repository does not contain any rulesets, then HTTP 404 Not Found.
  • Error of wrong URL (invalid parameters): HTTP 400 Bad Request


8.2.2 Get ruleset by ID

Retrieve a representation of the ruleset identified by [ruleset_id].

GET /[store_id]/repositories/[repository_id]/rulesets/[ruleset_id]?t=[token]
8.2.2.1 Response
  • A representation of the ruleset
 { 
  "id":"[ruleset_id]", 
  "name":{
           "en": "[name]",
           "[language]": "[name]"
         },
   "description": {
                    "en": "[description]",
                    "[language]": "[description]"
           },
   "metadata":{[metadata]},
   "rules": [
              {
                "id": "[rule_id1]",
                "name": {
                          "en": "[rule_name1]",
                          "[language]": "[rule_name1]"
                        }
               },
               ..., 
               {
                 "id": "[rule_idN]",
                 "name": {
                           "en": "[rule_nameN]",
                           "[language]": "[rule_nameN]"
                         }
               }
             ]
 }
  • If the ruleset does not contain any rules, then there will be an empty array
 { 
  "id":"[ruleset_id]", 
  "name":{
           "en": "[name]",
           "[language]": "[name]"
         },
   "description": {
                    "en": "[description]",
                    "[language]": "[description]"
           },
   "metadata":{[metadata]},
   "rules": []
 }

Errors:

  • No such ruleset: HTTP 404 Not Found
  • Wrong URL (invalid parameters): HTTP 400 Bad request


8.2.3 Get rulesets by name

Retrieve an array representation of all rulesets with the same [ruleset_name].

GET /[store_id]/repositories/[repository_id]/rulesets/name/[name]?t=[token]
8.2.3.1 Response
  • An array representation of all rulesets with the same [name] from this rule repository
 { 
  "id":"[repository_id]", 
  "name":"[name]",
  "description":"[description]", 
  "metadata":{[metadata]},
  "rulesets": [
             {
              "id": "[ruleset_id1]",
              "name": {
                       "en": "[ruleset_name]",
                       "[language]": "[ruleset_name]"
                      }
             },
             ...,
            ]
 }

Errors:

  • If the repository does not contain any rulesets with this [name], then HTTP 404 Not Found.
  • Wrong URL (invalid parameters): HTTP 400 Bad Request


8.2.4 Find rulesets (search)

Retrieve an array representation of all rulesets matching the [search_string]. Basically, the match is related to the ruleset description and metadata.

GET /[store_id]/repositories/[repository_id]/rulesets/search/[search_string]?t=[token]
8.2.4.1 Response
  • An array representation of all rulesets matching the [search_string] from this rule repository.
  • If the repository does not contain any rulesets matching the [search_string], then HTTP 404 Not Found
  • Wrong URL (invalid parameters): HTTP 400 Bad Request


8.3 Retrieving rules from a repository

8.3.1 Get all rules

Retrieve an array representation of the rules of this repository.

GET /[store_id]/repositories/[repository_id]/rules?t=[token]
8.3.1.1 Response
  • An array representation of all rules from this rule repository
 { 
   "id":"[repository_id]", 
   "name":"[name]",
   "description":"[description]", 
   "metadata":{[metadata]},
   "rules": [
             {
              "id": "[rule_id1]",
              "name": {
                       "en": "[rule_name1]",
                       "[language]": "[rule_name1]"
                      }
              },
               ..., 
              {
               "id": "[rule_idN]",
               "name": {
                         "en": "[rule_nameN]",
                         "[language]": "[rule_nameN]"
                       }
              }
             ]
 }

Errors:

  • If the repository does not contain any rules, then HTTP 404 Not Found
  • Wrong URL (invalid parameters): HTTP 400 Bad Request

8.3.2 Get rule by ID

Retrieve a representation of the rule identified by [rule_id].

GET /[store_id]/repositories/[repository_id]/rules/[rule_id]?t=[token]
8.3.2.1 Response
  • A representation of the rule
 { 
  "id":"[rule_id]", 
  "name":{
         "en": "[name]",
         "[language]": "[name]"
        },
  "description": {
                 "en": "[description]",
                 "[language]": "[description]"
          },
  "metadata":{[metadata]},
  "event": {[event]},
  "conditions": [...],
  "actions": [...]
 }

Errors:

  • No such rule: HTTP 404 Not Found
  • Error of wrong URL (invalid parameters): HTTP 400 Bad Request


8.3.3 Get rules by name

Retrieve an array representation of all rules with the same [name] from the repository [repository_id].

GET /[store_id]/repositories/[repository_id]/rules/name/[name]?t=[token]
8.3.3.1 Response
  • an array representation of all rules with the same [name] from this rule repository
 {
  "id":"[repository_id]", 
  "name":"[name]",
  "description":"[description]", 
  "metadata":{[metadata]},
  "rules": [
             {
              "id": "[rule_id1]",
              "name": {
                       "en": "[rule_name1]",
                       "[language]": "[rule_name1]"
                      }
             },
             ...,
          ]
 }

Errors:

  • If the repository does not contain any rules with this [name], then HTTP 404 Not Found
  • Wrong URL (invalid parameters): HTTP 400 Bad Request


8.3.4 Find rules (search)

Retrieve an array representation of all rules matching the [search_string]. Basically, the match is determined by the rule name, description and metadata.

GET /[store_id]/repositories/[repository_id]/rules/search/[search_string]?t=[token]
8.3.4.1 Response
  • An array representation of all rules matching the [search_string] from this rule repository.
 { 
  "id":"[repository_id]", 
  "name":"[name]",
  "description":"[description]", 
  "metadata":{[metadata]},
  "rules": [
             {
              "id": "[rule_id1]",
              "name": {
                        "en": "[rule_name1]",
                        "[language]": "[rule_name1]"
                      }
              },
              ...,
            ]
 }

Errors:

  • If the repository does not contain any rules matching the [search_string], then HTTP 404 Not Found
  • Wrong URL (invalid parameters): HTTP 400 Bad Request

9 Creating Resources

  • The client POSTs a representation of the resource to be created to the URI of the collection of which the resource should belong to.
  • If the resource was created successfully, the APIresponds with a HTTP status code 201 Created and a Location header that contains the URI of the newly created resource. Recall that the API is responsible with generating a URI of the resource.

9.1 Create a Repository

Creates a new (empty) repository with the following content:

  • a generated id, [repository_id],
  • a name [name]
  • a [metadata] description
  • NO rulesets. Rulesets can be added by new specific API requests
  • NO rules. Rules can be added by new specific API requests
POST /[store_id]/repositories/?t=[token]

A typical response is:

HTTP/1.1 201 Created
Location: http://ruletheweb.org/rulestore/[store_id]/repositories/[repository_id]/
...

9.2 Create a ruleset

Creates a new ruleset in the repository identified by [repository_id]. The new ruleset has

  • a generated id, [ruleset_id],
  • a name [name] - the English name of this ruleset
  • a [description] - a text description of this ruleset in English
  • a [metadata] - the metadata/annotations
  • [name] and [description] should be available in different languages identified by their ISO 639-1 country code. While English is required, any other additional language is possible.
  • NO rules. Rules can be added by new specific API requests


POST /[store_id]/repositories/[repository_id]/rulesets?t=[token]

9.2.1 Required parameters

  • [name]:Text the name of this ruleset using the English language
  • description:Text - a text description of this ruleset in English
  • [metadata] - the metadata/annotations of this ruleset

9.2.2 Response

HTTP/1.1 201 Created
Location: http://ruletheweb.org/rulestore/[store_id]/repositories/[repository_id]/rulesets/[ruleset_id]
...
  • Optionally, some implementation may consider to return a representation of the newly created ruleset:
 { 
  "id":"[ruleset_id]", 
  "name":{
          "en": "[name]",
          "[language]": "[name]"
          },
  "description": {
                  "en": "[description]",
                  "[language]": "[description]"
          },
   "metadata":{[metadata]}
 }

Errors:

  • Wrong parameters (no entity is created): HTTP 400
  • Wrong HTTP method in the request (other than HTTP POST): HTTP 405 Method Not Allowed

9.3 Create rule

Creates a new rule to the repository identified by [repository_id]. The new rule has

  • a generated id, [rule_id],
  • a name [name]
  • a [description] - text
  • [name] and [description] While English is required, any other additional language is possible.
  • [metadata] annotations
  • event
  • conditions
  • actions

Rules CANNOT be updated. When a rule change is necessary, it is required to delete the old rule and generate a new one.

POST /[store_id]/repository/[repository_id]/rules?t=[token]

A new global [rule_id] will be generated.

9.3.1 Required parameters

  • name - the name of this rule in English
  • description - a text description of this rule in English
  • metadata - the annotations of this rule
  • event - the event expression triggering this rule
  • conditions - rule conditions
  • actions - rule actions

9.3.2 Response

HTTP/1.1 201 Created
Location: http://ruletheweb.org/rulestore/[store_id]/repositories/[repository_id]/rules/[rule_id]
...
  • Optionally, some implementation may consider to return a representation of the newly created rule:
 { 
  "id":"[rule_id]", 
  "name":{
          "en": "[name]",
          "[language]": "[name]"
          },
  "description": {
                   "en": "[description]",
                   "[language]": "[description]"
          },
  "metadata":{[metadata]},
  "event": {[event]},
  "conditions": [...],
  "actions": [...]
 }

Errors:

  • Wrong parameters (no resource is created): HTTP 400 Bad request
  • Wrong HTTP method in the request (other than HTTP POST): HTTP 405 Method Not Allowed

10 Updating Resources

10.1 Update rulesets and rules

A ruleset can be updated by adding or deleting rules. Rules cannot be updated.

10.1.1 Adding a rule to a ruleset

Adding the rule referred to by [rule_id] to the ruleset referred to by [ruleset_id] with no duplicates. If the rule is already part of this ruleset, no action will take place. Basically, adding the rule [rule_id] to the ruleset [ruleset_id] is adding the [rule_id] to the ruleset collection(set) of rule IDs.

PUT /[store_id]/repositories/[repository_id]/rulesets/[ruleset_id]/rules/[rule_id]/?t=[token]
10.1.1.1 Preconditions
  • The rule must exist before the update request

(GET /[store_id]/repositories/[repository_id]/rules/[rule_id]?t=[token] must be successful ).

10.1.1.2 Required parameters

n/a

10.1.1.3 Response
  • A (summary) representation of the updated ruleset if successful update
{ 
  "id":"[ruleset_id]", 
  "name":{
           "en": "[name]",
           "[language]": "[name]"
         },
   "description": {
                    "en": "[description]",
                    "[language]": "[description]"
           },
   "metadata":{[metadata]},
   "rules": [
              {
                "id": "[rule_id]",
                "name": {
                          "en": "[rule_name1]",
                          "[language]": "[rule_name1]"
                        }
               },
               ...
            ]
 }
  • Wrong URL parameters (the ruleset is not updated): HTTP 400 Bad Request
  • The rule does not exist: HTTP 428 Precondition Required
  • Wrong HTTP method in the request (other than HTTP PUT): HTTP 405 Method Not Allowed


10.1.2 Deleting a rule from a ruleset

Deletes the rule referred to by [rule_id] from the ruleset referred to by [ruleset_id]. The rule MUST be part of the ruleset. Basically, when deleting the rule [rule_id] from the ruleset [ruleset_id], the [rule_id] is removed from the ruleset collection(set) of rule IDs.

DELETE /[store_id]/repositories/[repository_id]/rulesets/[ruleset_id]/rules/[rule_id]/?t=[token]
10.1.2.1 Required parameters

n/a

10.1.2.2 Response
  • A (summary) representation of the updated ruleset if update successful
 { 
  "id":"[ruleset_id]", 
  "name":{
           "en": "[name]",
           "[language]": "[name]"
         },
   "description": {
                    "en": "[description]",
                    "[language]": "[description]"
           },
   "metadata":{[metadata]},
   "rules": [ ... ]
 }
  • Wrong URL parameters (the ruleset is not updated): HTTP 400 Bad request
  • The rule to be deleted is not part of the ruleset: HTTP 412 Precondition Failed
  • Wrong HTTP method in request (not HTTP DELETE): HTTP 405 Method Not Allowed

11 Deleting Resources

11.1 Delete ruleset from a repository

Deletes the ruleset referred to by [ruleset_id] from the rule repository identified by [repository_id]. No rule is deleted.

DELETE /[store_id]/repositories/[repository_id]/rulesets/[ruleset_id]?t=[token]

11.1.1 Required parameters

n/a

11.1.2 Response

  • A (summary) representation of the deleted ruleset
  • Wrong URL (invalid parameters): HTTP 400 Bad request
  • Wrong HTTP method: HTTP 405 Method Not Allowed
  • The ruleset does not exist: 428 Precondition Required

11.2 Delete rule from repository

Deletes the rule referred to by [rule_id] from the rule repository identified by [repository_id].

DELETE /[store_id]/repositories/[repository_id]/rules/[rule_id]?t=[token]

11.2.1 Preconditions

The rule [rule_id] must exist and must not be referred to by any ruleset.

11.2.2 Required parameters

n/a

11.2.3 Response

  • A (summary) representation of the deleted rule
  • Wrong URL (invalid parameters): HTTP 400 Bad request
  • Wrong HTTP method: HTTP 405 Method Not Allowed
  • The rule does not exist or is referred to by ruleset(s): 428 Precondition Required

12 On REST Resources Pagination

Designing resource pagination is a know issue with some proposed solutions. The solution we consider to adopt is to DON'T MIX the resource as an answer with a pagination URL (such as the Facebook API is doing ) but rather to use the Link HTTP header (see also RFC5988 on Web Linking) such as:

Link: <http://ruletheweb/rulestore/[store_id]/repositories/[repository_id]/rules?t=[token]&offset=2>; rel="next", 

<http://ruletheweb/rulestore/[store_id]/repositories/[repository_id]/rules?t=[token]&offset=-2>; rel="previous"  \r\n

13 On Client Implementations

While some HTTP status codes are mentioned explicitly, clients should to be ready to handle any status code from an API implementation. A rule store server can choose to accept, reject, or delay the content submitted by a client. The same sequence of requests to two different rule stores may result in a different sequence of HTTP responses. Therefore the client software has to be flexibly written to accept what the server decides are the results of its submissions. Any API response or server content modification not explicitly forbidden by this specification is allowed.


14 Useful External Resources

15 References

  1. Bizer, Christian; Heath, Tom; Berners-Lee, Tim (2009). "Linked Data—The Story So Far". International Journal on Semantic Web and Information Systems 5 (3): 1–22. doi:10.4018/jswis.2009081901. ISSN 15526283, http://tomheath.com/papers/bizer-heath-berners-lee-ijswis-linked-data.pdf
  2. Fielding, Roy Thomas (2000), Architectural Styles and the Design of Network-based Software Architectures, Doctoral dissertation, University of California, Irvine, http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
  3. JavaScript Object Notation, http://json.org
  4. W3C XML Publications, http://www.w3.org/XML/Core/#Publications
  5. RuleML Primer, http://ruleml.org/papers/Primer
  6. JSR-94, http://jcp.org/en/jsr/detail?id=94
  7. API4KB, http://www.omgwiki.org/API4KB/doku.php
  8. 8.0 8.1 Hypertext Transfer Protocol -- HTTP/1.1 (RFC), http://tools.ietf.org/html/rfc2616
  9. List of HTTP status codes, http://en.wikipedia.org/wiki/HTTP_status_codes
  10. List of HTTP header fields, http://en.wikipedia.org/wiki/List_of_HTTP_header_fields
  11. D. Crockford, The application/json Media Type for JavaScript Object Notation (RFC54627), http://www.ietf.org/rfc/rfc4627.txt
  12. XML Schema Part 2: Datatypes Second Edition, W3C Recommendation 28 October 2004, http://www.w3.org/TR/xmlschema-2/
  13. Tim Berners-Lee, Linked Data , http://www.w3.org/DesignIssues/LinkedData.html
  14. Uniform Resource Identifier (URI): Generic Syntax, (RFC3986), http://tools.ietf.org/html/rfc3986
  15. Tim Berners-Lee, What HTTP URIs Identify, http://www.w3.org/DesignIssues/HTTP-URI2.html
  16. Jeni Tennison. What Do URIs Mean Anyway? http://www.jenitennison.com/blog/node/159