CAFE REST API Documentation

REST support has been provided so that users can access Cafe artifacts over http without having to write additional server side code.

Resources
- http://download.java.net/javaee5/sailfin-cafe/v1/rest/api//resources
  - http://download.java.net/javaee5/sailfin-cafe/v1/rest/api//resources//calls
  - http://download.java.net/javaee5/sailfin-cafe/v1/rest/api//resources//conferences
Representations

Resources

//resources

Communication resource is the entry point for all the different types of communications like Call , Conference Can be acessed using "/resource" context path. This resource is a JSR311 based rest resource.

Methods

//resources//calls

Calls REST resource that maps all the calls in the application. http://host:port/{contextroot}/resources/calls/{server/client}

Methods

//resources//calls//list

Methods

GET

Used to retrieve all the calls that are in progress. http://host:port/{contextroot}/resources/calls/list

available response representations:

application/xml
application/json

//resources//calls//server

Call resource maps one call in the system. It can be used to create or modify a call or retrived information corresponding to a call. http://host:port/{contextroot}/resources/calls/{server/client}/call/{callid}

Methods

//resources//calls//server//call/{callid}

resource-wide template parameters

parameter	value	description
callid	string	callid

Methods

GET

Retrieves the current status of the call if the callid is valid and belongs to this application. http://host:port/{contextroot}/resources/calls/{server/client}/call/{callid}

available response representations:

Status Code 200 - application/xml (ns3:CafeRestMessage)

PUT

Creates a call if the call id does not exist, or modifies the call if it exists. http://host:port/{contextroot}/resources/calls/{server/client}/call/{callid}

request query parameters

parameter	value	description
from	string	caller
to	string	callee.

available response representations:

Status Code 200 - application/xml (ns3:CafeRestMessage)

POST

Creates a call if the call id does not exist, or modifies the call if it exists. http://host:port/{contextroot}/resources/calls/{server/client}/call/{callid}

acceptable request representations:

application/xml
application/json

available response representations:

Status Code 200 - application/xml (ns3:CafeRestMessage)

DELETE

Ends a call. http://host:port/{contextroot}/resources/calls/{server/client}/call/{callid}

response header parameters

parameter	value	description
Callid	String	The deleted call id.

available response representations:

application/xml
application/json

//resources//calls//server//createcall

Methods

POST

Creates a call, used along with POST method. http://host:port/{contextroot}/resources/calls/{server/client}/createcall

acceptable request representations:

application/xml (ns3:CafeRestMessage)
application/json (ns3:CafeRestMessage)

available response representations:

Status Code 200 - application/xml (ns3:CafeRestMessage)

//resources//calls//client

Methods

//resources//conferences

Conferences REST resource that maps all the conferences in the application. http://host:port/resources/{contextroot}/conferences/{server/client}

Methods

//resources//conferences//list

Methods

GET

Used to retrieve all the calls that are in progress. http://host:port/{contextroot}/resources/conferences/list

available response representations:

application/xml
application/json

//resources//conferences//server

Conference resource maps one conference in the system. It can be used to create or modify a conference or retrived information corresponding to a conference. http://host:port/{contextroot}/resources/conferences/{server/client}/conference/{conferenceid}

Methods

//resources//conferences//server//conference/{conferenceid}

resource-wide template parameters

parameter	value	description
conferenceid	string	conference id

Methods

GET

Retrieves the current status of the conference if the id is valid and belongs to this application. http://host:port/{contextroot}/resources/conferences/{server/client}/conference/{conferenceid}

available response representations:

Status Code 200 - application/xml (ns3:CafeRestMessage)

PUT

Creates a conference if the id does not exist, or modifies the call if it exists. http://host:port/{contextroot}/resources/conferences/{server/client}/conference/{conferenceid}

acceptable request representations:

application/xml (ns3:CafeRestMessage)
application/json (ns3:CafeRestMessage)

available response representations:

Status Code 200 - application/xml (ns3:CafeRestMessage)

DELETE

Ends a conference. http://host:port/{contextroot}/resources/conferences/{server/client}/conference/{conferenceid}

response header parameters

parameter	value	description
Conference id	String	The deleted Conference id.

available response representations:

application/xml
application/json

//resources//conferences//server//createconference

Methods

POST

Should be used to create a conference with a server generated conference id. The create with the PUT method should be used when the client wants to supply the call id.

acceptable request representations:

application/xml (ns3:CafeRestMessage)
application/json (ns3:CafeRestMessage)

available response representations:

Status Code 200 - application/xml (ns3:CafeRestMessage)

//resources//conferences//server//conference/{conferenceid}/add

resource-wide template parameters

parameter	value	description
conferenceid	string	conference id

Methods

POST

Adds a participant from the conference. Should be POST and not PUT because we cannot gurantee idempotency with PUT. We could use PUT if we model Participant as a resource.

acceptable request representations:

application/xml
application/json

available response representations:

application/xml
application/json

//resources//conferences//server//conference/{conferenceid}/add/{participantid}

resource-wide template parameters

parameter	value	description
participantid	string
conferenceid	string	conference id

Methods

PUT

Adds a participant from the conference. Should be POST and not PUT because we cannot gurantee idempotency with PUT. We could use PUT if we model Participant as a resource.

available response representations:

application/xml
application/json

//resources//conferences//server//conference/{conferenceid}/remove

resource-wide template parameters

parameter	value	description
conferenceid	string	conference id.

Methods

POST

Removes a participant from the conference.

acceptable request representations:

application/xml
application/json

available response representations:

application/xml
application/json

//resources//conferences//server//conference/{conferenceid}/remove/{participantid}

resource-wide template parameters

parameter	value	description
participantid	string
conferenceid	string	conference id.

Methods

DELETE

Removes a participant from the conference.

available response representations:

application/xml
application/json

//resources//conferences//client

Methods

Representations

application/xml

application/json

Status Code 200 - application/xml (ns3:CafeRestMessage)

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cafeRestMessage xmlns="http://sailfin-cafe.dev.java.net/schema/cafe-rest-types">
    <cafeRestResponse>
        <call>
            <from>
                <name>alice@sailfin-cafe.org</name>
                <nickname>Alice</nickname>
                <status>ACTIVE</status>
            </from>
            <to>
                <name>bob@sailfin-cafe.org</name>
                <nickname>Bob</nickname>
                <status>ACTIVE</status>
            </to>
            <id>samplecallid</id>
            <status>INACTIVE</status>
        </call>
    </cafeRestResponse>
</cafeRestMessage>

Status of the call after completion.

XML Schema

Source:

Status Code 200 - application/xml (ns3:CafeRestMessage)

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cafeRestMessage xmlns="http://sailfin-cafe.dev.java.net/schema/cafe-rest-types">
    <cafeRestResponse>
        <call>
            <from>
                <name>alice@sailfin-cafe.org</name>
                <nickname>Alice</nickname>
                <status>ACTIVE</status>
            </from>
            <to>
                <name>bob@sailfin-cafe.org</name>
                <nickname>Bob</nickname>
                <status>ACTIVE</status>
            </to>
            <id>samplecallid</id>
            <status>INACTIVE</status>
        </call>
    </cafeRestResponse>
</cafeRestMessage>

Status of the call after completion.

XML Schema

Source:

application/xml

application/json

Status Code 200 - application/xml (ns3:CafeRestMessage)

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cafeRestMessage xmlns="http://sailfin-cafe.dev.java.net/schema/cafe-rest-types">
    <cafeRestResponse>
        <call>
            <from>
                <name>alice@sailfin-cafe.org</name>
                <nickname>Alice</nickname>
                <status>ACTIVE</status>
            </from>
            <to>
                <name>bob@sailfin-cafe.org</name>
                <nickname>Bob</nickname>
                <status>ACTIVE</status>
            </to>
            <id>samplecallid</id>
            <status>INACTIVE</status>
        </call>
    </cafeRestResponse>
</cafeRestMessage>

Status of the call after completion.

XML Schema

Source:

application/xml

application/json

application/xml (ns3:CafeRestMessage)

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cafeRestMessage xmlns="http://sailfin-cafe.dev.java.net/schema/cafe-rest-types">
    <cafeRestRequest>
        <call>
            <from>
                <name>alice@sailfin-cafe.org</name>
                <nickname>Alice</nickname>
                <status>ACTIVE</status>
            </from>
            <to>
                <name>bob@sailfin-cafe.org</name>
                <nickname>Bob</nickname>
                <status>ACTIVE</status>
            </to>
            <id></id>
            <status></status>
        </call>
    </cafeRestRequest>
</cafeRestMessage>

XML Schema

Source:

application/json (ns3:CafeRestMessage)

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cafeRestMessage xmlns="http://sailfin-cafe.dev.java.net/schema/cafe-rest-types">
    <cafeRestRequest>
        <call>
            <from>
                <name>alice@sailfin-cafe.org</name>
                <nickname>Alice</nickname>
                <status>ACTIVE</status>
            </from>
            <to>
                <name>bob@sailfin-cafe.org</name>
                <nickname>Bob</nickname>
                <status>ACTIVE</status>
            </to>
            <id></id>
            <status></status>
        </call>
    </cafeRestRequest>
</cafeRestMessage>

XML Schema

Source:

Status Code 200 - application/xml (ns3:CafeRestMessage)

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cafeRestMessage xmlns="http://sailfin-cafe.dev.java.net/schema/cafe-rest-types">
    <cafeRestResponse>
        <call>
            <from>
                <name>alice@sailfin-cafe.org</name>
                <nickname>Alice</nickname>
                <status>ACTIVE</status>
            </from>
            <to>
                <name>bob@sailfin-cafe.org</name>
                <nickname>Bob</nickname>
                <status>ACTIVE</status>
            </to>
            <id>samplecallid</id>
            <status>INACTIVE</status>
        </call>
    </cafeRestResponse>
</cafeRestMessage>

Status of the call after completion.

XML Schema

Source:

application/xml

application/json

Status Code 200 - application/xml (ns3:CafeRestMessage)

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cafeRestMessage xmlns="http://sailfin-cafe.dev.java.net/schema/cafe-rest-types">
    <cafeRestResponse>
        <conference>
            <originator>
                <name>alice@sailfin-cafe.org</name>
                <nickname>Alice</nickname>
                <status>ACTIVE</status>
            </originator>
            <participant>
                <name>alice@sailfin-cafe.org</name>
                <nickname>Alice</nickname>
                <status>ACTIVE</status>
            </participant>
            <participant>
                <name>bob@sailfin-cafe.org</name>
                <nickname>Bob</nickname>
                <status>ACTIVE</status>
            </participant>
            <id>sampleconferenceid</id>
            <status>ACTIVE</status>
        </conference>
    </cafeRestResponse>
</cafeRestMessage>

Status of the call after completion.

XML Schema

Source:

application/xml (ns3:CafeRestMessage)

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cafeRestMessage xmlns="http://sailfin-cafe.dev.java.net/schema/cafe-rest-types">
    <cafeRestResponse>
        <conference>
            <originator>
                <name>alice@sailfin-cafe.org</name>
                <nickname>Alice</nickname>
                <status>ACTIVE</status>
            </originator>
            <participant>
                <name>alice@sailfin-cafe.org</name>
                <nickname>Alice</nickname>
                <status>ACTIVE</status>
            </participant>
            <participant>
                <name>bob@sailfin-cafe.org</name>
                <nickname>Bob</nickname>
                <status>ACTIVE</status>
            </participant>
            <id></id>
            <status></status>
        </conference>
    </cafeRestResponse>
</cafeRestMessage>

XML Schema

Source:

application/json (ns3:CafeRestMessage)

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cafeRestMessage xmlns="http://sailfin-cafe.dev.java.net/schema/cafe-rest-types">
    <cafeRestResponse>
        <conference>
            <originator>
                <name>alice@sailfin-cafe.org</name>
                <nickname>Alice</nickname>
                <status>ACTIVE</status>
            </originator>
            <participant>
                <name>alice@sailfin-cafe.org</name>
                <nickname>Alice</nickname>
                <status>ACTIVE</status>
            </participant>
            <participant>
                <name>bob@sailfin-cafe.org</name>
                <nickname>Bob</nickname>
                <status>ACTIVE</status>
            </participant>
            <id></id>
            <status></status>
        </conference>
    </cafeRestResponse>
</cafeRestMessage>

XML Schema

Source:

Status Code 200 - application/xml (ns3:CafeRestMessage)

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cafeRestMessage xmlns="http://sailfin-cafe.dev.java.net/schema/cafe-rest-types">
    <cafeRestResponse>
        <conference>
            <originator>
                <name>alice@sailfin-cafe.org</name>
                <nickname>Alice</nickname>
                <status>ACTIVE</status>
            </originator>
            <participant>
                <name>alice@sailfin-cafe.org</name>
                <nickname>Alice</nickname>
                <status>ACTIVE</status>
            </participant>
            <participant>
                <name>bob@sailfin-cafe.org</name>
                <nickname>Bob</nickname>
                <status>ACTIVE</status>
            </participant>
            <id>sampleconferenceid</id>
            <status>ACTIVE</status>
        </conference>
    </cafeRestResponse>
</cafeRestMessage>

Status of the call after completion.

XML Schema

Source:

application/xml

application/json

application/xml (ns3:CafeRestMessage)

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cafeRestMessage xmlns="http://sailfin-cafe.dev.java.net/schema/cafe-rest-types">
    <cafeRestResponse>
        <conference>
            <originator>
                <name>alice@sailfin-cafe.org</name>
                <nickname>Alice</nickname>
                <status>ACTIVE</status>
            </originator>
            <participant>
                <name>alice@sailfin-cafe.org</name>
                <nickname>Alice</nickname>
                <status>ACTIVE</status>
            </participant>
            <participant>
                <name>bob@sailfin-cafe.org</name>
                <nickname>Bob</nickname>
                <status>ACTIVE</status>
            </participant>
            <id></id>
            <status></status>
        </conference>
    </cafeRestResponse>
</cafeRestMessage>

XML Schema

Source:

application/json (ns3:CafeRestMessage)

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cafeRestMessage xmlns="http://sailfin-cafe.dev.java.net/schema/cafe-rest-types">
    <cafeRestResponse>
        <conference>
            <originator>
                <name>alice@sailfin-cafe.org</name>
                <nickname>Alice</nickname>
                <status>ACTIVE</status>
            </originator>
            <participant>
                <name>alice@sailfin-cafe.org</name>
                <nickname>Alice</nickname>
                <status>ACTIVE</status>
            </participant>
            <participant>
                <name>bob@sailfin-cafe.org</name>
                <nickname>Bob</nickname>
                <status>ACTIVE</status>
            </participant>
            <id></id>
            <status></status>
        </conference>
    </cafeRestResponse>
</cafeRestMessage>

XML Schema

Source:

Status Code 200 - application/xml (ns3:CafeRestMessage)

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cafeRestMessage xmlns="http://sailfin-cafe.dev.java.net/schema/cafe-rest-types">
    <cafeRestResponse>
        <conference>
            <originator>
                <name>alice@sailfin-cafe.org</name>
                <nickname>Alice</nickname>
                <status>ACTIVE</status>
            </originator>
            <participant>
                <name>alice@sailfin-cafe.org</name>
                <nickname>Alice</nickname>
                <status>ACTIVE</status>
            </participant>
            <participant>
                <name>bob@sailfin-cafe.org</name>
                <nickname>Bob</nickname>
                <status>ACTIVE</status>
            </participant>
            <id>sampleconferenceid</id>
            <status>ACTIVE</status>
        </conference>
    </cafeRestResponse>
</cafeRestMessage>