6

RESTful EPCIS API Specification

6.1. Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

46

6.2. Event EPCIS Vocabulary to RESTful EPCIS Vocabulary Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

47

6.3. Query EPCIS Vocabulary to RESTful EPCIS Vocabulary Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

49

6.4. Error Code to HTTP Status Code Mapping . . . . . . . . . . 51 6.5. XML Representation Template . . . . . . . . . . . . . . . . . . 51

6.1. Description Chapter 6 and 7 specify the RESTful EPCIS API. All resources are bundled into the following functional groups. Home Section 7.1 Configuration Section 7.2 About Section 7.3 Query Section 7.4 Subscription Creator Section 7.5 Subscription Section 7.6 Capture Section 7.7 Event finder Section 7.8 The resources are structured into URI templates according to the tree structure illustrated by Figure 6.1. The root resource is also the home of the RESTful EPCIS. The URI for each resource is defined as the concatenation of all node labels of the path starting from the root and ending by the node of the resource in question. There are two kinds of resources: container resources and single resources. Container resources Container Resources are represented as a list containing links to their sub-resources.

46

6.2. Event EPCIS Vocabulary to RESTful EPCIS Vocabulary Mapping

47

Single resources Single Resources are concrete instances and each of them have an individual representation. Container resources respond only to HTTP GET. Single Resources can respond to the uniform interface ranging from HTTP GET, POST, PUT to DELETE. Additionally all resources are responding to HTTP HEAD and OPTIONS. GET GET is used to get a representation of the corresponding resource indicated by the URI. POST POST is used to create or update a resource, but let the application decide to which URI the new resource will be assigned to or if the resource already exists how the resource shall be changed. PUT PUT is used to create or update a resource, but let the user decide in the URI to which URI the new resource will be assigned to or if the resource already exists how the resource shall be changed. DELETE DELETE removes the resource specified under the according URI. HEAD HEAD is used to get only the HTTP header of the response without any content. OPTIONS OPTIONS returns the WADL (see Appendix C) for the according resource including the base URI of the REST application, resources, sub-resources, resource methods with request and response representation and so on. All resources respond to different representation formats specified by the MIME type of the request HTTP ACCEPTS header. The mapping is defined as follows: text/html XHTML representation of the resource. application/xhtml+xml XHTML core representation of the resource without the RESTful EPCIS web page layout. application/xml XML representation of the resource specified by XML Schema B.9 of the RESTful EPCIS. text/xml XML representation, strictly following the XML Schema B.1 of the EPCIS standard [EPC07]. application/json JSON representation specified by the standard translation of JAX-RS implemented by Jersey to translate an XML Document compliant to XML Schema B.9 to JSON. Subsection 6.5 illustrates the template that indicates how the XML resource representation is structured.

6.2. Event EPCIS Vocabulary to RESTful EPCIS Vocabulary Mapping Table 6.1 specifies the mapping for the names of the event fields accessible through /EVENT_URL/RESTFUL_EPCIS_VOCABULARY_NAME. As an example the URI /EVENT_URL/action will return the value of the action field of that event. The available fields for a specific event type is defined in [EPC07] chapter 7.2.8 - 7.2.12 from page 40 to 55. The meaning of the fields are explained in the EPCGlobal EPCIS specification

6.2. Event EPCIS Vocabulary to RESTful EPCIS Vocabulary Mapping

Figure 6.1.: Resources

48

6.3. Query EPCIS Vocabulary to RESTful EPCIS Vocabulary Mapping

49

cited above. When there is no such field for a specific type of event, the response does not contain any content.

RESTful vocabulary ID

Table 6.1.: Event Type Vocabulary Mapping EPCIS EPCIS Vocabulary Description (not supported)

type

(not supported)

time recordtime (not supported)

eventTime recordTime eventTimeZoneOffset

transactions epcs

bizTransList epcList, childEPCs

action parentid epcclass quantity step disposition reader location

action parentID epcClass quantity bizStep disposition readPoint bizLocation

The URI is also the ID of the Event - does not exist in the EPCIS The type of the Event: ObjectEvent, AggregationEvent, QuantityEvent or AggregationEvent Event Time Record Time Time Zone Offset - does not have any URI for itself in the RESTful EPCIS, it is only on available on the event overview Transaction List EPC List - an EPCIS event can either contain an epcList or childEPCs, therefore they are both mapped to epcs Action Parent ID EPC Class Quantity Business Step Disposition Read Point Business Location

6.3. Query EPCIS Vocabulary to RESTful EPCIS Vocabulary Mapping The EPCIS Specification [EPC07] defines a set of query parameters in chapter 8.2.7.1 SimpleEventQuery on page 75. Single values are encoded as string values, whereas multiple values are encoded as a comma separated concatenated string. The vocabulary of the EPCIS query parameters are mapped to the RESTful EPCIS vocabulary as follows: eventType type GE_eventTime time, where the time is encoded as >value

6.3. Query EPCIS Vocabulary to RESTful EPCIS Vocabulary Mapping

50

LT_eventTime time, where the time is encoded as value LT_recordTime recordtime, where the recordtime is encoded as value GE_quantity quantity, where the quantity is encoded as >value-1 LT_quantity quantity, where the quantity is encoded as SERVER_URL / e p c i s / r e s t / 1 . 0 /RESOURCEPATH< / u r i > RESOURCE NAME< / name> < d e s c r i p t i o n >RESOURCE DESCRIPTION< / d e s c r i p t i o n > epcis< / value> SERVER_URL/ e p c i s / < / valueRef > r e s t < / value> SERVER_URL/ e p c i s / r e s t / < / valueRef > 1.0< / value> SERVER_URL/ e p c i s / r e s t / 1 . 0 / < / valueRef > < v a l u e >SUBRESOURCE< / v a l u e > SERVER_URL/ e p c i s / r e s t / 1 . 0 /SUBRESOURCEPATH< / valueRef > < / treeMenu> < v a l u e >CONTENT VALUE 1< / v a l u e > CONTENT VALUE 1 URL< / valueRef > < / content> < v a l u e >CONTENT VALUE N< / v a l u e > CONTENT VALUE N URL< / valueRef > < / content> OBJECT EVENT ELEMENTS ( i f any ) < / objectEvents> AGGREGATION EVENT ELEMENTS ( i f any ) < / aggregationEvents> QUANTITY EVENT ELEMENTS ( i f any ) < / quantityEvents> TRANSACTION EVENT ELEMENTS ( i f any ) < / transactionEvents> FORM ELEMENTS ( i f any ) < / form> QUERY RESULTS ELEMENTS ( i f any ) < / queryResults> POLL ELEMENTS ( i f any ) < / ns2:resource>

Listing 6.1: XML Representation Template

7

RESTful EPCIS API Resources Specification

7.1. Home . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

54

7.2. Configuration Interface . . . . . . . . . . . . . . . . . . . . . . .

55

7.2.1. EPCIS URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

56

7.2.2. FEED URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

58

7.2.3. Reset RESTful EPCIS . . . . . . . . . . . . . . . . . . . . . . .

59

7.2.4. Reload Finder . . . . . . . . . . . . . . . . . . . . . . . . . . . .

60

7.3. About . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

62

7.3.1. Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

63

7.3.2. Query Names . . . . . . . . . . . . . . . . . . . . . . . . . . . .

66

7.3.3. Authors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

68

7.4. Simple Event Query Form . . . . . . . . . . . . . . . . . . . . .

69

7.4.1. Event Query Results . . . . . . . . . . . . . . . . . . . . . . . .

72

7.5. Subscription Creation . . . . . . . . . . . . . . . . . . . . . . . .

73

7.6. Subscription List . . . . . . . . . . . . . . . . . . . . . . . . . . .

75

7.6.1. Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

76

7.7. Capture Interface . . . . . . . . . . . . . . . . . . . . . . . . . .

77

7.7.1. Capture Simulator . . . . . . . . . . . . . . . . . . . . . . . . .

79

7.8. Event Finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

80

7.8.1. Business Location List . . . . . . . . . . . . . . . . . . . . . . .

80

7.8.2. Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

81

7.8.3. Reader List . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

82

7.8.4. Reader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

83

7.8.5. Time List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

84

7.8.6. Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

85

7.8.7. Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

86

7.8.8. Event Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

88

53

54

7.1. Home 7.8.9. Event Sub Member Collection . . . . . . . . . . . . . . . . . . .

89

7.9. RESTful API . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

91

Each resource specification of the RESTful EPCIS API is structured as follows: Resource Name The name of the resource. Description A short description of the resource. EPCIS Specification Equivalent If the resource has an equivalent in the EPCIS Specification [EPC07], the corresponding reference to the EPCIS Specification is described here. URI The URI of the resource. Comment The comment describes the resource in more details. Overview The overview describes the behavior and requirements of applying valid HTTP methods to the resource URI. HTTP method name The name of the HTTP method. Description Describes what happens if the HTTP method is applied to the URI of the resource. Produces Lists all the MIME types for which the resource has a corresponding representation. Consumes (only available if the resource consumes something) Lists all the MIME types that the resource accepts in the HTTP request body. Representation of consumed media (only available if the resource consumes something) A description how the consumed media must be encoded. Example of consumed media (only available if the resource consumes something) An example of a consumed media. HTTP status code The HTTP status code that the resource returns if everything went well. Representation XML Response A description of the XML representation. Representation XHTML Response A description of the XHTML representation. Example XHTML Response An example of a XHTML representation. Method Overview A Table that presents an overview of the resource. The table describes which HTTP methods are applicable to the resource URI and what will happen thereby.

7.1. Home Resource Name: Home Description: The RESTful EPCIS home. EPCIS Specification Equivalent: -

55

7.2. Configuration Interface

Figure 7.1.: Home URI: REST_URL/ Comment: Contains a list of links to direct sub-resources. Overview: • GET

Description List of links to the following sub-resources: Query Form 7.4, Browsable Event Finder 7.8, Subscription Creation 7.5, Subscription Interface 7.6, Capture Interface 7.7, Configuration 7.2, About 7.3. Produces text/html, application/xhtml+xml, application/html, text/xml, application/json HTTP status code 200: OK - The request has been responded as expected. Representation XML Response Element restfulEPCISContent (lines 27 - 36) of Listing 6.5 (lines 27 - 36) containing the links in compliance to XML Schema of Listing B.9. Representation XHTML Response List of anker elements referencing the subresources. Example XHTML Response The Figure 7.1 shows how a Web browser displays the XHTML representation.

Table 7.1 shows an overview of the methods the resource is responding to.

URI / Method REST_URL/config

Table 7.1.: Method Overview: Home GET PUT POST Deliver links to home’s sub-resources

7.2. Configuration Interface Resource Name: Configuration Description: The interface to configure the RESTful EPCIS.

DELETE -

56

7.2. Configuration Interface

Figure 7.2.: Configuration EPCIS Specification Equivalent: URI: REST_URL/config Comment: Contains a list of links to specific configuration resources. Overview: • GET

Description List of links to the following configuration resources: EPCIS URL Configuration 7.2.1, FEED URL Configuration 7.2.2, Reset RESTful EPCIS 7.2.3, Reload Finder 7.2.4. Produces text/html, application/xhtml+xml, application/html, text/xml, application/json HTTP status code 200: OK - The request has been responded as expected. Representation XML Response Element restfulEPCISContent (lines 27 - 36) of Listing 6.5 containing the links in compliance to XML Schema of Listing B.9. Representation XHTML Response List of anker elements referencing the subresources. Example XHTML Response The Figure 7.2 shows how a Web browser displays the XHTML representation.

Table 7.2 shows an overview of the methods the resource is responding. Table 7.2.: Method Overview: Description URI / Method GET PUT POST REST_URL/config Deliver links to specific configuration resources

7.2.1. EPCIS URL Resource Name: EPCIS URL Configuration Description: The interface to set the EPCIS URL.

DELETE -

7.2. Configuration Interface

57

Figure 7.3.: Configuration EPCIS URL EPCIS Specification Equivalent: URI: REST_URL/config/epcisurl Comment: Resource to handle the EPCIS to which the RESTful EPCIS interface is set to. This is indicated by the URL of the corresponding EPCIS. Overview: • GET

Description Gets a form indicating how the EPCIS URL can be changed. Produces text/html, application/xhtml+xml, application/html, text/xml, application/json HTTP status code 200: OK - The request has been responded as expected. Representation XML Response Element form (lines 50 - 52) of Listing 6.5 indicates the actual EPCIS URL. It also contains the URI and HTTP method to use, to send the new EPCIS URL. The URI to be used is the URI of the EPCIS URL configuration resource and HTTP PUT must be used to send the new EPCIS URL in the request body. The XML is in compliance to XML Schema of Listing B.9. Representation XHTML Response Form to change the EPCIS URL. Example XHTML Response The Figure 7.3 shows how a Web browser displays the XHTML representation.

• PUT

Description Changes the URL to the one indicated in the HTTP body. Consumes text/plain Representation consumed text The new URL as pure string. Example consumed text http://localhost:8080/epcis-repository-0.4.2 Produces text/html, application/xhtml+xml, application/html, text/xml, application/json HTTP status code 200: OK - The request has been responded as expected. Representation Response Message indicating that the update was successful.

Table 7.3 shows an overview of the methods the resource is responding.

7.2. Configuration Interface

58

Table 7.3.: Method Overview: Configuration EPCIS URL URI / Method GET PUT POST DELETE REST_URL/config/ Deliver a Set the EP- epcisurl form to set CIS to the the EPCIS URL inURL dicated in the message body

7.2.2. FEED URL Resource Name: Feed URL Configuration Description: The interface to set the feed URL. EPCIS Specification Equivalent: URI: REST_URL/config/feedurl Comment: Resource to handle the feed to which the subscribed events shall be reported to. This is indicated by the URL of the corresponding feed. Overview: • GET

Description Gets a form indicating how the feed URL can be changed. Produces text/html, application/xhtml+xml, application/html, text/xml, application/json HTTP status code 200: OK - The request has been responded as expected. Representation XML Response Element form (lines 50 - 52) of Listing 6.5 indicates the actual feed URL. It also contains the URI and HTTP method to use, to send the new feed URL. The URI to be used is the URI of the feed URL configuration resource and HTTP PUT must be used to send the new feed URL in the request body. The XML is in compliance to XML Schema of Listing B.9. Representation XHTML Response Form to change the feed URL. Example XHTML Response The Figure 7.4 shows how a Web browser displays the XHTML representation.

• PUT

Description Changes the URL to the one indicated in the HTTP body. Consumes text/plain Representation consumed text The new URL as pure string.

7.2. Configuration Interface

59

Figure 7.4.: Configuration Feed URL Example consumed text http://localhost:8080/epcis/rest/feed Produces text/html, application/xhtml+xml, application/html, text/xml, application/json HTTP status code 200: OK - The request has been responded as expected. Representation Response Message indicating that the update was successful. Table 7.4 shows an overview of the methods the resource is responding. Table 7.4.: Method Overview: Configuration Feed URL URI / Method GET PUT POST DELETE REST_URL/config/ Deliver a Set the feed feedurl form to set to the URL the feed URL indicated in the message body

7.2.3. Reset RESTful EPCIS Resource Name: Reset RESTful EPCIS Description: The interface to reset the RESTful EPCIS. EPCIS Specification Equivalent: URI: REST_URL/config/resetrestfulepcis Comment: Resource to handle the re-initialization of the RESTful EPCIS. This includes initializing the Event Finder, setting the default EPCIS and feed URL as well as clear all persistent data, including subscriptions and feed data. Overview: • GET

Description Gets a form indicating how the RESTful EPCIS can be reset. Produces text/html, application/xhtml+xml, application/html, text/xml, application/json

60

7.2. Configuration Interface

Figure 7.5.: Reset RESTful EPCIS HTTP status code 200: OK - The request has been responded as expected. Representation XML Response Element form (lines 50 - 52) of Listing 6.5 containing the URL of the action which is self and that HTTP method POST shall be used, all in compliance to XML Schema of Listing B.9. Representation XHTML Response Form to reset the RESTful EPCIS. Example XHTML Response The Figure 7.5 shows how a Web browser displays the XHTML representation. • POST

Description Resets the RESTful EPCIS. Consumes all MIME types Representation consumed type This resource does not consume any message body. Example consumed text empty string Produces text/html, application/xhtml+xml, application/html, text/xml, application/json HTTP status code 200: OK - The request has been responded as expected. Representation Response Message indicating that the reset was successful.

Table 7.5 shows an overview of the methods the resource is responding. Table 7.5.: Method Overview: Reset RESTful EPCIS URI / Method GET PUT POST REST_URL/config/ Deliver a Resets the resetrestfulepcis form to reset RESTful the RESTful EPCIS EPCIS

7.2.4. Reload Finder Resource Name: Reload Event Finder Description: The interface to reload the Event Finder. EPCIS Specification Equivalent: URI: REST_URL/config/reloadfinder

DELETE -

61

7.2. Configuration Interface

Figure 7.6.: Reload Event Finder Comment: Resource to handle the reload of the Event Finder. This includes the extraction of all business locations in the EPCIS as well as all according read points to be able to create the Event Finder. Whenever the EPCIS URL changes or new locations and readers are added, this resource shall be used to be able to use this data in the Event Finder. Reloading the Event Finder is resource intensive and should be done only when necessary. Overview: • GET

Description Gets a form indicating how the Event Finder can be reloaded. Produces text/html, application/xhtml+xml, application/html, text/xml, application/json HTTP status code 200: OK - The request has been responded as expected. Representation XML Response Element form (lines 50 - 52) of Listing 6.5 containing the URL of the action which is self and that HTTP method POST shall be used, all in compliance to XML Schema of Listing B.9. Representation XHTML Response Form to reload the Event Finder. Example XHTML Response The Figure 7.6 shows how a Web browser displays the XHTML representation.

• POST

Description Reloads the Event Finder. Consumes all MIME types Representation consumed type This resource does not consume any message body. Example consumed text empty string Produces text/html, application/xhtml+xml, application/html, text/xml, application/json HTTP status code 200: OK - The request has been responded as expected. Representation Response Message indicating that the reload was successful.

Table 7.6 shows an overview of the methods the resource is responding. Table 7.6.: Method Overview: Reload Event Finder URI / Method GET PUT POST REST_URL/config/ Deliver a Reloads the reloadfinder form to Event Finder reload the Event Finder

DELETE -

62

7.3. About

Figure 7.7.: About

7.3. About Resource Name: About Description: About the RESTful EPCIS. EPCIS Specification Equivalent: URI: REST_URL/about Comment: Contains a list of links to resources about the RESTful EPCIS. Overview: • GET

Description List of links to the following sub-resources: About Version Information 7.3.1, About Query Names 7.3.2, About Authors 7.3.3. Produces text/html, application/xhtml+xml, application/html, text/xml, application/json HTTP status code 200: OK - The request has been responded as expected. Representation XML Response Element restfulEPCISContent (lines 27 - 36) of Listing 6.5 containing the links in compliance to XML Schema of Listing B.9. Representation XHTML Response List of anker elements referencing the subresources. Example XHTML Response The Figure 7.7 shows how a Web browser displays the XHTML representation.

Table 7.7 shows an overview of the methods the resource is responding.

URI / Method REST_URL/about

Table 7.7.: Method Overview: About GET PUT POST Deliver links to about’s sub-resources

DELETE -

63

7.3. About

Figure 7.8.: Version

7.3.1. Version Resource Name: Version Description: Version Information about the RESTful EPCIS. EPCIS Specification Equivalent: URI: REST_URL/about/version Comment: Contains a list of links of version the following version information: RESTful EPCIS, EPCIS implementation and EPCIS specification. Overview: • GET

Description List of links to the following sub-resources: RESTful EPCIS Version 7.3.1, EPCIS implementation 7.3.1, EPCIS specification 7.3.1. Produces text/html, application/xhtml+xml, application/html, text/xml, application/json HTTP status code 200: OK - The request has been responded as expected. Representation XML Response Element restfulEPCISContent (lines 27 - 36) of Listing 6.5 containing the version in compliance to XML Schema of Listing B.9. Representation XHTML Response Version as text. Example XHTML Response The Figure 7.8 shows how a Web browser displays the XHTML representation.

Table 7.8 shows an overview of the methods the resource is responding.

URI / Method REST_URL/about/ version

Table 7.8.: Method Overview: Version GET PUT POST Deliver the RESTful EPCIS version

DELETE -

64

7.3. About

Figure 7.9.: REST Version REST Version Resource Name: RESTful EPCIS Version Description: About the RESTful EPCIS Version. EPCIS Specification Equivalent: URI: REST_URL/about/version/rest Comment: The Representation of the vendor version of the RESTful EPCIS implementation. Overview: • GET

Description Gets the version of the RESTful EPCIS implementation. Produces text/html, application/xhtml+xml, application/html, text/xml, application/json HTTP status code 200: OK - The request has been responded as expected. Representation XML Response Element form (lines 50 - 52) of Listing 6.5 containing the URL of the action which is self and that HTTP method POST shall be used, all in compliance to XML Schema of Listing B.9. Representation XHTML Response Form to reset the RESTful EPCIS. Example XHTML Response The Figure 7.9 shows how a Web browser displays the XHTML representation.

Table 7.9 shows an overview of the methods the resource is responding. Table 7.9.: Method Overview: REST Version URI / Method GET PUT POST REST_URL/about/ Deliver the version/rest RESTful EPCIS version

Standard Version Resource Name: Standard Version

DELETE -

65

7.3. About

Figure 7.10.: Standard Version Description: The standard version of the EPCIS. EPCIS Specification Equivalent: EPCIS Specification [EPC07] chapter 8.2.5 on page 62. Method getStandardVersion() : string of the EPCISQueryControlInterface. URI: REST_URL/about/version/standard Comment: The Specification defines to return a string for the standard version representation. Can cause SecurityException, ValidationException and ImplementationException. Overview: • GET

Description Represents the standard version of the EPCIS the RESTful interface is set on. Produces text/html, application/xhtml+xml, application/html, text/xml, application/json HTTP status code 200: OK - The request has been responded as expected. Representation XHTML Response A string containing the standard version. Example XHTML Response "1.0" as illustrated by the Figure 7.10 which shows how a Web browser displays the XHTML representation.

Table 7.10 shows an overview of the methods the resource is responding. Table 7.10.: Method Overview: Standard Version URI / Method GET PUT POST REST_URL/about/ Deliver the version/standard standard version

Vendor Version Resource Name: Vendor Version Description: The vendor version of the EPCIS implementation.

DELETE -

66

7.3. About

Figure 7.11.: Vendor Version EPCIS Specification Equivalent: EPCIS Specification [EPC07] chapter 8.2.5 on page 62. Method getVendorVersion() : string of the EPCISQueryControlInterface. URI: REST_URL/query/SMD/vendorVersion Comment: The Representation of the vendor version is vendor specific and not defined by the standard. If there are no extensions from the standard, and the implementation is following exactly the standard the empty string shall represent this behavior. Can cause SecurityException, ValidationException and ImplementationException. Overview: • GET

Description Represents the vendor version of the EPCIS the RESTful interface is set on. Produces text/html, application/xhtml+xml, application/html, text/xml, application/json HTTP status code 200: OK - The request has been responded as expected. Representation XHTML Response A string containing the vendor version or the empty string. Example XHTML Response The Figure 7.11 shows how a Web browser displays the XHTML representation.

Table 7.11 shows an overview of the methods the resource is responding. Table 7.11.: Method Overview: Vendor Version URI / Method GET PUT POST REST_URL/about/ Deliver the version/standard vendor version

7.3.2. Query Names Resource Name: Query Names Description: The query names that the EPCIS supports.

DELETE -

67

7.3. About

Figure 7.12.: Query Names EPCIS Specification Equivalent: EPCIS Specification [EPC07] chapter 8.2.5 on page 62. Method getQueryNames() : List of String (list of names) of the EPCISQueryControlInterface. URI: REST_URL/query/SMD/queryNames Comment: Returns a list of query names. The default query names are: 1. Simple Event Query and 2. Master Data Query. Others are implementation and extension specific. Can cause SecurityException, ValidationException and ImplementationException. Overview: Description Produces text/html HTTP status code 200: OK - The request has been responded as expected. Representation XHTML Response A list of strings. Example XHTML Response "SimpleEventQuery", "MasterDataQuery" • GET

Description The list of query names the EPCIS supports. Produces text/html, application/xhtml+xml, application/html, text/xml, application/json HTTP status code 200: OK - The request has been responded as expected. Representation XHTML Response A list of strings containing of supported query names. Example XHTML Response The Figure 7.12 shows how a Web browser displays the XHTML representation.

Table 7.12 shows an overview of the methods the resource is responding. Table 7.12.: Method Overview: Query Names URI / Method GET PUT POST REST_URL/about/ Deliver a list querynames of supported query names

DELETE -

68

7.3. About

Figure 7.13.: Authors

7.3.3. Authors Resource Name: Authors Description: About the authors of the RESTful EPCIS. EPCIS Specification Equivalent: URI: REST_URL/about/authors Comment: Contains a list of links of to the authors of the RESTful EPCIS. Overview: • GET

Description List of links to the authors 7.3.3. Produces text/html, application/xhtml+xml, application/html, text/xml, application/json HTTP status code 200: OK - The request has been responded as expected. Representation XML Response Element restfulEPCISContent (lines 27 - 36) of Listing 6.5 containing the links in compliance to XML Schema of Listing B.9. Representation XHTML Response List of anker elements referencing the subresources. Example XHTML Response The Figure 7.13 shows how a Web browser displays the XHTML representation.

Table 7.15 shows an overview of the methods the resource is responding.

URI / Method REST_URL/about/ authors

Table 7.13.: Method Overview: Authors GET PUT POST Deliver links to the authors

Author Resource Name: Author

DELETE -

69

7.4. Simple Event Query Form

Figure 7.14.: Author Description: The interface to present an author of the RESTful EPCIS including the name, email address and organization. EPCIS Specification Equivalent: URI: REST_URL/about/authors/AUTHOR_ID Comment: Presents an author of the RESTful EPCIS. Overview: • GET

Description Gets author name, email address and organization including corresponding URI’s. Produces text/html, application/xhtml+xml, application/html, text/xml, application/json HTTP status code 200: OK - The request has been responded as expected. Representation XML Response Element restfulEpcisContent (lines 27 - 36) of Listing 6.5 containing the name, email address and organization with the corresponding references, all in compliance to XML Schema of Listing B.9. Representation XHTML Response List of author data. Example XHTML Response The Figure 7.14 shows how a Web browser displays the XHTML representation.

Table 7.14 shows an overview of the methods the resource is responding.

URI / Method REST_URL/config/ resetrestfulepcis

Table 7.14.: Method Overview: Author GET PUT POST Deliver au- thor data

7.4. Simple Event Query Form Resource Name: Simple Event Query Form Description: A form to create simple event queries.

DELETE -

70

7.4. Simple Event Query Form

EPCIS Specification Equivalent: URI: REST_URL/eventquery{queryparams} Comment: Contains a form to build a RESTful simple event query. Overview: • GET

Description The representation of this resource is a form including form entries to set the RESTful EPCIS query parameters. A form entry consists of a name, a value and an optional description. The value of a form entry corresponds to the URL query parameter from the URL of this resource. This means that if URL query parameter x with value y is supplied to this resource, the form entry with name x also has as value y. This gives the advantage of bookmark-able forms. The description can indicate how a value shall be encoded. The action of the form consists of sending an HTTP GET to the query results resource 7.4.1 supplying the query form entries as name value pairs encoded as URL query parameters. Produces text/html, application/xhtml+xml, application/html, text/xml, application/json HTTP status code 200: OK - The request has been responded as expected. Representation XML Response Element form (lines 50 - 52) of Listing 6.5 containing the query parameters as form entries indicating that HTTP GET shall be used to the action URL for event query results 7.4.1 including the query parameters constructed from the form, all in compliance to XML Schema of Listing B.9. Representation XHTML Response HTML form holding input types to create the corresponding query parameters to the URL for event query results 7.4.1. Example XHTML Response The Figure 7.15 shows how a Web browser displays the XHTML representation for the following URI: REST_URL/eventquery?epc=urn:epc:id:sgtin:0101010.101010.0042& location=urn:epc:id:sgln:unifr.perolles&action=OBSERVE.

Table 7.15 shows an overview of the methods the resource is responding. Table 7.15.: Method Overview: Query Form URI / Method GET PUT POST REST_URL/eventquery Deliver a {queryparams} form to build queries

DELETE -

71

7.4. Simple Event Query Form

Figure 7.15.: Query Form

7.4. Simple Event Query Form

72

7.4.1. Event Query Results Resource Name: Simple Event Query Results Description: The interface to query the EPCIS for EPC-related events. EPCIS Specification Equivalent: EPCIS Specification [EPC07] chapter 8.2.5 on page 62. Method poll("SimpleEventQuery", params : QueryParams): QueryResults of the EPCISQueryControlInterface. URI: REST_URL/eventquery/result{queryparams} Whereby queryparams is defined as follows: string starting with a “?” containing a list of name/value pairs separated by a “&”. name is one of the supported arguments and value is a delimited list of argument values as specified in Table 7.16. Multiple name/value pairs can be used together in order to further confine the scope of the query. The more name/value pairs are added, the more specific the resource of interest would be. Comment: Contains a list of event query results, where a result is an event 7.8.7. This resource also includes a button to subscribe to the according query. When the subscription is created, it shall contain a link to the subscription resource 7.6.1. Can cause NoSuchNameException, QueryParameterException, QueryTooComplexException, QueryTooLargeException, SecurityException, ValidationException and ImplementationException.

Table 7.16.: REST-based Scoping of supported EPCIS Arguments Parameter Type Separator Example Simple Type or SinQUERY_URL?epc=abcxyz gle Argument (Integer, Float, String, ...) Unordered List , QUERY_URL?action=ADD,OBSERVE Relationships (e.g QUERY_URL?time=