Junos Space SDK > Developer Guides > Junos Space Application Developer Guide > Programming with the Junos Space SDK > Reference Applications > HelloWorld

Consuming HelloWorld APIs using the REST Client

This topic gives an exposition of REST interfaces or APIs for the HelloWorld application. The examples below demonstrate the HTTP semantics for consuming HelloWorld APIs.

All APIs documented in this topic were created using the SDK EJB-REST Wizard.

You can validate HTTP operations using the SDK REST Explorer.

HelloWorld exposes five CRUD APIs for each DTO Resource (five for countries and five for states) and four additional CRUD APIs for country-states mapping. There is also a single Asynchronous API.

Countries CRUD APIs:

States CRUD APIs:

Country-States Mapping APIs

Asynchronous APIs (LRR)

Note that there could also potentially be these additional missing APIs:

Description
API
Media Type
Replace a list of all countries (or states): PUT /api/jssdk/hello-world/world/countries application/vnd.jssdk.hello-world.world.countries+xml;version=1)
Replace a list of states for a country: PUT /api/jssdk/hello-world/world/countries/5/states application/vnd.jssdk.hello-world.world.states-ref+xml;version=1)
Add a list of additional countries (or states): POST /api/jssdk/hello-world/world/countries application/vnd.jssdk.hello-world.world.countries+xml;version=1)
Add a list of addtional states to a country: POST /api/jssdk/hello-world/world/countries/5/state application/vnd.jssdk.hello-world.world.states-ref+xml;version=1)
Update/Modify a list of all countries: PATCH /api/jssdk/hello-world/world/countries application/vnd.jssdk.hello-world.world.countries-patch+xml;version=1)

Countries CRUD APIs

To add a new country

Request

POST           : /api/jssdk/hello-world/world/countries  
HTTP/1.1 Host : <host-name>:<port>
Authorization : Basic c3VwZXI6anVuaXBlcjEyMw==
Accept : application/vnd.jssdk.hello-world.world.country+xml;version=1
Content type : application/vnd.jssdk.hello-world.world.country+xml;version=1 <country>
<name>France</name>
<population>323434</population>
</country>

Response

Status Code  : 200 OK 
Content-type : application/vnd.jssdk.hello-world.world.country+xml;q="0.01";version="1"

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<country uri="/api/jssdk/hello-world/world/countries/8">
<id>8</id>
<name>France</name>
<population>323434</population>
<states uri="/api/jssdk/hello-world/world/countries/8/states" />
</country>

To get a list of all countries

Request

GET           : /api/jssdk/hello-world/world/countries
HTTP/1.1 Host: <host-name>:<port>
Authorization : Basic c3VwZXI6anVuaXBlcjEyMw==
Accept        : application/vnd.jssdk.hello-world.world.countries+xml;version=1

Response

Status Code  : 200 OK 
Content-type : application/vnd.jssdk.hello-world.world.countries+xml;q="0.01";version="1"

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<countries uri="/api/jssdk/hello-world/world/countries" size="3">
<country href="/api/jssdk/hello-world/world/countries/5" uri="/api/jssdk/hello-world/world/countries/5">
<id>5</id>
<name>Japan</name>
<population>127720000</population>
</country>
<country href="/api/jssdk/hello-world/world/countries/6" uri="/api/jssdk/hello-world/world/countries/6">
<id>6</id>
<name>Russia</name>
<population>142914136</population>
</country>
<country href="/api/jssdk/hello-world/world/countries/7" uri="/api/jssdk/hello-world/world/countries/7">
<id>7</id>
<name>United States</name>
<population>312587000</population>
</country>
</countries>

To get a country by ID

Request

GET           : /api/jssdk/hello-world/world/countries/{countryID}      
HTTP/1.1 Host : <host-name>:<port>
Authorization : Basic c3VwZXI6anVuaXBlcjEyMw==
Accept        : application/vnd.jssdk.hello-world.world.country+xml;version=1

Response

Status Code  : 200 OK 
Content-type : application/vnd.jssdk.hello-world.world.country+xml;q="0.01";version="1"

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<country uri="/api/jssdk/hello-world/world/countries/7">
<id>7</id>
<name>United States</name>
<population>312587000</population>
<states uri="/api/jssdk/hello-world/world/countries/7/states">
<state uri="/api/jssdk/hello-world/world/countries/7/states/4"
href="/api/jssdk/hello-world/world/states/4">
<id>4</id>
<name>California</name>
<population>878652</population>
</state>
<state uri="/api/jssdk/hello-world/world/countries/7/states/9"
href="/api/jssdk/hello-world/world/states/9">
<id>9</id>
<name>Nevada</name>
<population>983214</population>
</state>
<state uri="/api/jssdk/hello-world/world/countries/7/states/11"
href="/api/jssdk/hello-world/world/states/11">
<id>11</id>
<name>New York</name>
<population>234135</population>
</state>
</states>
</country>

To replace a country by ID

Note that we specifically say that this is a complete "replace" of the country, and not an "update" or a "modify".

Request

PUT           : /api/jssdk/hello-world/world/countries/{countryid}      
HTTP/1.1 Host : <host-name&gt:<port>
Authorization : Basic c3VwZXI6anVuaXBlcjEyMw==
Content-type  : application/vnd.jssdk.hello-world.world.country+xml;version=1
Accept        : application/vnd.jssdk.hello-world.world.country+xml;version=1

<country>
<name>Russia</name>
<population>234456</population>
</country>

Response

Status Code  : 200 OK 
Content-type : application/vnd.jssdk.hello-world.world.country+xml;q="0.01";version="1"

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<country uri="/api/jssdk/hello-world/world/countries/6">
<id>6</id>
<name>Russia</name>
<population>234456</population>
<states uri="/api/jssdk/hello-world/world/countries/6/states" />
</country>

To delete a country by ID

Request

DELETE        : /api/jssdk/hello-world/world/countries/{countryId}
HTTP/1.1 Host : <host-name&gt:<port>
Authorization : Basic c3VwZXI6anVuaXBlcjEyMw==

Response

Status Code : 204 No Content


Country-States Mapping API's:

To add a state to an existing country

Request

POST          : /api/jssdk/countries/{countryId}/states
HTTP/1.1 Host : <host-name>:<port>
Authorization : Basic c3VwZXI6anVuaXBlcjEyMw==
Content-type  :	application/vnd.jssdk.hello-world.world.state-ref+xml;version=1;charset=UTF-8

<state href="/api/jssdk/hello-world/world/states/14"/>

Response

Status Code  : 200 OK
Content-Type: application/vnd.jssdk.hello-world.world.state-ref+xml;q="0.01";version="1"

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<state href="/api/jssdk/hello-world/world/states/14" uri="/api/jssdk/hello-world/world/countries/7/states/14">
<id>14</id>
<name>Oklahoma</name>
<population>76868</population>
</state>

To get a list of all the states within a country

Request

GET           : /api/jssdk/hello-world/world/countries/{countryId}/states 
HTTP/1.1 Host: <host-name>:<port>
Authorization : Basic c3VwZXI6anVuaXBlcjEyMw==
Accept        : application/vnd.jssdk.hello-world.world.states-ref+xml;version=1

Response

Status Code  : 200 OK
Content-type : application/vnd.jssdk.hello-world.world.states-ref+xml;q="0.01";version="1"

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<states href="/api/jssdk/hello-world/world/states" uri="/api/jssdk/hello-world/world/countries/7/states">
<state href="/api/jssdk/hello-world/world/states/4" uri="/api/jssdk/hello-world/world/countries/7/states/4">
<id>4</id>
<name>California</name>
<population>878652</population>
</state>
<state href="/api/jssdk/hello-world/world/states/11" uri="/api/jssdk/hello-world/world/countries/7/states/11">
<id>11</id>
<name>New York</name>
<population>234135</population>
</state>
<state href="/api/jssdk/hello-world/world/states/14" uri="/api/jssdk/hello-world/world/countries/7/states/14">
<id>14</id>
<name>Oklahoma</name>
<population>76868</population>
</state>
</states>

To get a state within a country providing country ID and state ID

Request

GET           : /api/jssdk/hello-world/world/countries/{countryId}/states/{stateId}
HTTP/1.1 Host: <host-name>:<port>
Authorization : Basic c3VwZXI6anVuaXBlcjEyMw==
Accept        : application/vnd.jssdk.hello-world.world.state-ref+xml;version=1

Response

Status Code  : 200 OK
Content-type : application/vnd.jssdk.hello-world.world.state-ref+xml;q="0.01";version="1"

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>  
<state href="/api/jssdk/hello-world/world/states/4" uri="/api/jssdk/hello-world/world/countries/7/states/4">
<id>4</id>
<name>California</name>
<population>878652</population>
</state>

To delete a state from a country

Request

DELETE        : /api/jssdk/hello-world/world/countries/{countryId}/states/{stateId}
HTTP/1.1 Host : <host-name>:<port>
Authorization : Basic c3VwZXI6anVuaXBlcjEyMw==

Response

Status Code: 204 No Content

Asynchronous APIs (LRR)

To execute a Long Running Request (LRR)

To run "Countries Report", HelloWorld utilizes the LRR mechanism of Hornet-Q. For a more detailed description of this mechanism and LRRs, see Implementing Asynchronous Services (LRR).

1. Create a queue

Request

POST          : /api/hornet-q/queues
HTTP/1.1 Host : <host-name&gt:<port>
Authorization : Basic c3VwZXI6anVuaXBlcjEyMw==
Content-type  : application/hornetq.jms.queue+xml

<queue name="test">
  <durable>false</durable>
</queue>

Note: To create a durable queue, change the value to "true".

Response

Status Code : 201 Created
Location    : http://127.0.0.1:8080/api/hornet-q/queues/jms.queue.test

2. Schedule a Long Running request passing in "test" queue as a parameter

Request

POST          : /api/jssdk/hello-world/world/run-countries-report?queue=http://127.0.0.1:8080/api/hornet-q/queues/jms.queue.test
HTTP/1.1 Host : <host-name>:<port>
Authorization : Basic c3VwZXI6anVuaXBlcjEyMw==
Content-type  : application/xml

<queue name="test"> <durable>false</durable> </queue>

Note: To create a durable queue, change the value to "true".

Response

Status Code  : 202 Accepted	
Content-type : application/vnd.net.juniper.space.job-management.task+xml;q="0.01";version="1"
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<task href="/api/space/job-management/jobs/229385">
<id>229385</id>
</task>
 

For further instructions on how to create a queue consumer and fetch progress update, see Create a Queue Consumer.