How to use EMIR API?
--------------------

The EMI Registry allows Services to register/publish their capabilities
while the Service Consumers are able to find the deployed services.

This section contains the description of the REST-ful interface, that allows the
management of the service information (or entries) by exposing the individual
URIs. The normative description of the API cab also be defined as Web Application Description Language (WADL) document xref:appendixii[WADL].

Creatung OR Updating the Service Endpoint Records
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+HTTP Method+ : PUT

+URI+ : /serviceadmin

+Content Type+ : application/json

+Security Implications+ : Requires an authenticated "and" authorized client's access to perform this operation

Request
^^^^^^^

The request body contain a similar JSON array object as defined in xref:appendixi[], it contains
description of the Services to be updated or created. The endpoint records will be updated automatically,
 if the JSON document in the request body is already existing. The operation takes place only after the 
 successful authentication and authorisation checks. 

Response
^^^^^^^^

The response contains an array of JSON Objects as it was sent in the request, confirming the successful update.

+Status Code+ : OK / 200

Delete existing Services
~~~~~~~~~~~~~~~~~~~~~~~~

+HTTP Method+ : DELETE

+URI+ : /serviceadmin

+Security Implications+ : Requires an authenticated "and" authorized user access to perform this operation

Request
^^^^^^^

The Service Entry matching the Endpoint ID will be deleted from the
registry only if the client executing the action has authorised access and the 
method is allowed by the security plugins.

+URL Query Parameters+ : Service_Endpoint_ID= _<Service Endpoint ID>_

******
*Example* : /serviceadmin?Service_Endpoint_ID=urn:endpoint:emi1
******

Response
^^^^^^^^

+Status Code+ : OK / 200

Query for Endpoint Information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+HTTP Method+ : GET

+URI+ : /services

+Content Type+ : application/json

Request
^^^^^^^

The request contains the key-value pairs separated by ampersand +&+

+Query Parameters+ : AttributeName=<Attribute_Value>&AttributeName=<Attribute_Value>&...

*******
*Example* : /services?Service_Type=eu.emi.es&Service_Endpoint_HealthState=ok
*******

The response contains an array of service entries packed in a JSON array object 

+Status Code+ : OK / 200

Rich Querying in EMIR
~~~~~~~~~~~~~~~~~~~~~~

+HTTP Method+ : GET

+URI+ : /services

+Content Type+ : application/json

Request
^^^^^^^

The request contains the JSON document including with support for defining advanced clauses, the
http://www.mongodb.org/display/DOCS/Advanced+Queries, MongoDB Advanced Queries[MongoDB JSON Query Language] describes the various types of queries

Additional keys (skip, limit) can also be added to paginate the returning results.

Response
^^^^^^^^

The response contains the array of service entries packed in a JSON array object 

+Status Code+ : OK / 200

Querying the EMIR for GLUE 2.0 XML Documents
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+HTTP Method+ : GET

+URI+ : /services

+Content Type+ : application/xml

Request
^^^^^^^

The request contains the key-value pairs separated by ampersand +&+

+Query Parameters+ : AttributeName=<Attribute_Value>&AttributeName=<Attribute_Value>&...

*******
*Example* : /services?Service_Type=eu.emi.es&Service_Endpoint_HealthState=ok
*******

Response
^^^^^^^^

The response contains an XML document containing service entries in GLUE 2.0 format 

+Status Code+ : OK / 200

Rich Querying the EMIR for GLUE 2.0 XML Documents
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The request and response interface is same as defined above, however the content type must be 
defined as *application/xml* instead.

Traversing through Query Results
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

It is very likely that a client (plain or rich) query can evaluate to a huge number of result set, 
which may result in memory over-flow and delayed response. In order to make the listing scalable and
faster response times of the query requests, a traversal mechanism has been implemented 
at the Web services as well as JAVA client layer. It allows a client to provide specific query parameters, 
while offering the two alternative ways, thus highly depending on the size of EMIR index. 

[NOTE]
======================

The same iterating parameters can be used for the available query methods, 
such as, with query parameters or rich querying

======================

Using +skip+ and +limit+ Query Parameters 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*skip* defines an offset or a number of records to be skipped from the query result
 
*limit* defines a total number of resulting endpoints expected from the query


Following example illustrates this method of traversal:

Request
+++++++

+GET / POST:+		/services/?skip=<Non-Negative Number>&limit=<Non-Negative Number>

_Example Usage:_ 	https://emir.example.org/services?skip=10&limit=100

+Content-Type:+		application/json OR application/xml
    
Response
++++++++

An array of matching endpoint records, either in a JSON or an XML format depending on the Content-Type header

************

This method is suitable when size of endpoint records 
stored in the EMIR server is not larger than 1000.

************

Using +pageSize+ and +ref+ Query Parameters 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Being a memory efficient and robust, this method is ought to be the most preferable way of traversing the 
endpoint records.  

*pageSize* defines a total number of resulting endpoint records expected from a query
 
*ref* every returned page contains a reference or pointer to the next page for further traversal
  
Following example illustrates this method of traversal:

Request
+++++++

+GET / POST:+		/services/pageSize=<Non-Negative Number>&ref=<String>

_Example Usage:_	https://emir.example.org/services?pageSize=10&ref=87701693-ca33-482c-bbf4-843f9952e012

+Content-Type:+ 		application/json OR application/xml
    
Response
++++++++

An array of matching endpoint records, either in a JSON or an XML format depending on the Content-Type header

Faceted Search
~~~~~~~~~~~~~~

The EMIR offers a remote interface to faceted search based on the endpoint attributes. The purpose of the
feature is to get the frequency (or count) of endpoint attribute's values.The request is using simple URL 
query parameters to the +/services/facet+ URI. Furthermore, the query is attribute type specific, the 
query parameters should specify the type while sending the request. The response of the faceted query contains
requested attributes and associated values with frequency.  

Request
+++++++

+GET:+				/services/facet?<Attribute Name>:(facet.simple|facet.type)     

Example showing the faceted search for two different types of attributes: simple +Service_Type+, +Service_Endpoint_Capabilities+ 

_Example Usage:_	https://emir.example.org/services/facet?Service_Type=facet.simple&Service_Endpoint_Capabilities=facet.array

Response
++++++++

The response contains a JSON array containing the Attributes grouped by their values and their frequency of
occurrence.

.Example Facet Response
------------
include::facet-example.json[]
------------   

Viewing the Service information template
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This To view the GLUE 2.0's JSON flavored service model.

+HTTP Method+ : GET 

+URI+ : /model

+Content Type+ : application/json

Request
^^^^^^^

N/A

Response
^^^^^^^^

A JSON document containing all the mandatory and optional attribute 

Information about the Deployed EMIR Server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There is an Web services interface to query the EMIR server's status in JSON format. This specifically
contains the following attributes:

* EMIRServerVersion
* MongoDBVersion
* JavaVersion
* OSName
* OSArchitecture
* OSVersion
* EMIRServerComponentName
* AnonymousAccessPortNumber
* RunningSince
* NumberofEntries

+HTTP Method+: GET

+URI+: /status

+Content-Type+: application/json

Request
^^^^^^^

N/A

Response
^^^^^^^^

A JSON document containing the aforementioned attributes

+Status Code+ : OK / 200

.Example Status Information
------------
include::status.json[]
------------