username: password: remember me
Create a new GroupMe! account
GroupMe!
RESTful API

RESTful API

GroupMe!'s RESTful API is actually a Semantic Web based RESTful API, because data that is exchanged between your client application and GroupMe! is semantically well-defined RDF. Currently, we use the following schemas to wrap GroupMe! data.


Schemas:
  • FOAF - the Friend of the Friend vocabulary is used to describe the GroupMe! users as well as documents
  • DCMI - from the Dublin Core Metadata Terms we use terms like dc:description, dc:title, etc. to describe the GroupMe! resources
  • Tag Ontology - the Tag Ontology models tag assignments done in GroupMe!
  • GroupMe! Ontology - the GroupMe! Ontology defines new concepts such as GroupMe! groups

The RDF-based RESTful API implements the following HTTP methods.


  1. GET: Enables client application to receive RDF representations of users, tags, resources, and GroupMe! groups.
  2. POST: Client applications that want to create new GroupMe! content can post the RDF representation of the content to GroupMe!

OAuth Authorization

Client applications can create new GroupMe! content (e.g., creating a new group) or they can access also private data of the user. Therefor, client applications have to be authorized by the user. Here, GroupMe! supports the OAuth Protocol. GroupMe!'s OAuth authorization endpoints are:



Whenever new content should be created on behalf of the user or private data of the user should be accessed then the client has to send his OAuth credentials to GroupMe!. For more details on OAuth, we can recommend you the Getting Started Tutorial at http://oauth.net and have a look at the overview diagram illustrating the protocol flow. Further, we encourage you to make use of the programming libraries available at http://code.google.com/p/oauth/ or simply drop us a mail.
Java Web application developers anyhow do not have to worry about OAuth protocol handling and GroupMe!-specific RDF-(de)serialization as they can make use of the Client API module.


1. GET

GroupMe! RDF data can be accessed via HTTP.GET. In particular, each the RDF representation of a GroupMe! entity (i.e. user, tag, resource, or GroupMe! group) can be accessed with simple HTTP.GET requests. Here, GroupMe! adheres to the principles of Linked Data.


There are two ways how a client application can tell GroupMe! that it wants to receive RDF representations:


  1. Via preferences about the preferred accepted media type. In particular, this means that in the Accept HTTP Header field the client indicates that application/rdf+xml is the preferred media type he wants to receive.
    Example: 

    Accept: text/plain; q=0.5, text/html; q=0.8, application/rdf+xml

    The example above is an extract of an HTTP header, where the Accept field can be interpreted as follows: application/rdf+xml is the most preferred media type, text/html is the second best preferred media type (as it just has a quality factor of 0.8), and text/plain is the least preferred media type (as it just has a quality factor of 0.5).
  2. Via an extra parameter in the HTTP query string. If a client application appends ?output=rdf to the URL of a users, tag, resource, or GroupMe! group, then its RDF representation is returned (independently of what is specified in the HTTP Accept Header field.

Examples: Access the RDF representation of a




1.1 List GroupMe! groups of current user

If a user accesses http://groupme.org/GroupMe/home/groups then he sees his GroupMe! groups. Client applications can access the RDF representation of these groups.
Method: http://groupme.org/GroupMe/home/groups?output=rdf
Returns: the RDF representation of the GroupMe! groups created by the user
Example result: http://groupme.org/GroupMe/home/groups?output=rdf




2. POST

For all following POST operations provided by the GroupMe! API, the client applications have to submit the required OAuth parameters such as oauth_token.


2.1 Create a new GroupMe! group

Method: http://groupme.org/GroupMe/home/create-new-group
Parameter: rdf
Value of rdf: the RDF representation of the group that should be created (ID/URI of the group can be selected arbitrary as they are replaced anyhow when the GroupMe! group is created properly).
Returns: the RDF representation of the GroupMe! group (with a valid URI) that was actually created
Example:
The HTTP request that is posted to http://groupme.org/GroupMe/home/create-new-group might look as follows:


POST  /GroupMe/home/create-new-group  HTTP/1.1
Host: http://groupme.org
Accept: application/rdf+xml
	
oauth_token: c6b8ece703858cc0da977c72c3c4fb74 
oauth_consumer_key: groupmewebclient 
oauth_signature_method: HMAC-SHA1
oauth_timestamp: 1236728948 
oauth_nonce: 1236728948600883000
oauth_version: 1.0
oauth_signature: 9VWFYuQIrf7SHpLCktd9b5qfegQ%3D							    
rdf: 
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
	xmlns:gm="http://groupme.org/rdf/groupme.owl#"
	xmlns:dc="dc"
	xmlns:foaf="http://xmlns.com/foaf/0.1/"
	xmlns:tags="http://www.holygoat.co.uk/owl/redwood/0.1/tags/#"
	xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">

<rdf:Description rdf:about="http://groupme.org/GroupMe/group/test-group">
	<rdf:type rdf:resource="http://groupme.org/rdf/groupme.owl#Group"/>
	<title xmlns="http://purl.org/dc/elements/1.1/">Test-1236729123776</title>
	<description xmlns="http://purl.org/dc/elements/1.1/">test description</description>
	<foaf:maker rdf:resource="http://groupme.org/GroupMe/user/test"/>
	<tags:taggedWithTag rdf:resource="http://groupme.org/GroupMe/tag/test-tag"/>
</rdf:Description>

<rdf:Description rdf:about="http://groupme.org/GroupMe/tag/test-tag">
	<rdf:type rdf:resource="http://www.holygoat.co.uk/owl/redwood/0.1/tags/#Tag"/>
	<tags:name>test-tag</tags:name>
</rdf:Description>

<rdf:Description rdf:about="http://groupme.org/GroupMe/resource/1">
	<rdf:type rdf:resource="http://xmlns.com/foaf/0.1/Document"/>
	<title xmlns="http://purl.org/dc/elements/1.1/">test resource</title>
	<description xmlns="http://purl.org/dc/elements/1.1/">test resource description</description>
	<seeAlso xmlns="http://www.w3.org/2000/01/rdf-schema#" rdf:resource="http://example.org"/>
	<tags:taggedWithTag rdf:resource="http://groupme.org/GroupMe/tag/res-tag"/>
</rdf:Description>

<rdf:Description rdf:about="http://groupme.org/GroupMe/tag/res-tag">
	<rdf:type rdf:resource="http://www.holygoat.co.uk/owl/redwood/0.1/tags/#Tag"/>
	<tags:name>res-tag</tags:name>
</rdf:Description>

<rdf:Description rdf:about="http://groupme.org/GroupMe/group/test-group">
	<gm:contains rdf:resource="http://groupme.org/GroupMe/resource/1"/>
</rdf:Description>

</rdf:RDF>

In the example, the group (http://groupme.org/GroupMe/group/test-group) that is posted to the GroupMe! system, contains one resource (http://groupme.org/GroupMe/resource/1), which is annotated with with a tag res-tag. The group itself has a tag as well: test-tag. If the client application (groupmewebclient) is authorized, i.e. if the oauth_token is valid, then the group will be created within the GroupMe! system and the following RDF representation of the group will be returned: 


<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
	xmlns:gm="http://groupme.org/rdf/groupme.owl#"
	xmlns:dc="dc"
	xmlns:foaf="http://xmlns.com/foaf/0.1/"
	xmlns:tags="http://www.holygoat.co.uk/owl/redwood/0.1/tags/#"
	xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">

<rdf:Description rdf:about="http://groupme.org/GroupMe/group/2825">
	<rdf:type rdf:resource="http://groupme.org/rdf/groupme.owl#Group"/>
	<title xmlns="http://purl.org/dc/elements/1.1/">Test-1236729123776</title>
	<description xmlns="http://purl.org/dc/elements/1.1/">test description</description>
	<foaf:maker rdf:resource="http://groupme.org/GroupMe/user/fabian"/>
	<tags:taggedWithTag rdf:resource="http://groupme.org/GroupMe/tag/test-tag"/>
</rdf:Description>

<rdf:Description rdf:about="http://groupme.org/GroupMe/tag/test-tag">
	<rdf:type rdf:resource="http://www.holygoat.co.uk/owl/redwood/0.1/tags/#Tag"/>
	<tags:name>test-tag</tags:name>
</rdf:Description>

<rdf:Description rdf:about="http://groupme.org/GroupMe/resource/2765">
	<rdf:type rdf:resource="http://xmlns.com/foaf/0.1/Document"/>
</rdf:Description>

<rdf:Description rdf:about="http://groupme.org/GroupMe/group/2825">
	<gm:contains rdf:resource="http://groupme.org/GroupMe/resource/2765"/>
</rdf:Description>
</rdf:RDF>

2.2 Add a Resource to a GroupMe! group

Method: http://groupme.org/GroupMe/group/[ID_OF_GROUP] (URL of the group to which the resource should be added)
Parameter: rdf
Value of rdf: the RDF representation of the resource that should be added to the group (ID/URI of the resource can be selected arbitrary as they are replaced anyhow when the GroupMe! group is created properly).
Returns: the RDF representation of the GroupMe! group into which the resource was added
Remarks:


  • http://groupme.org/GroupMe/group/[ID_OF_GROUP] has to be a group, which is owned by the user, the client application is acting for.
  • the actual URL of the resource has to be submitted within the rdfs:seeAlso field

Example:
The HTTP request that is posted to http://groupme.org/GroupMe/group/[ID_OF_GROUP] might look as follows:


POST  /GroupMe/group/1508  HTTP/1.1
Host: http://groupme.org
Accept: application/rdf+xml
	
oauth_token: c6b8ece703858cc0da977c72c3c4fb74 
oauth_consumer_key: groupmewebclient 
oauth_signature_method: HMAC-SHA1
oauth_timestamp: 1236728948 
oauth_nonce: 1236728948600883000
oauth_version: 1.0
oauth_signature: 9VWFYuQIrf7SHpLCktd9b5qfegQ%3D							    
rdf: 
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
	xmlns:gm="http://groupme.org/rdf/groupme.owl#"
	xmlns:dc="dc"
	xmlns:foaf="http://xmlns.com/foaf/0.1/"
	xmlns:tags="http://www.holygoat.co.uk/owl/redwood/0.1/tags/#"
	xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">

<rdf:Description rdf:about="http://groupme.org/GroupMe/resource/id-not-yet-set">
	<rdf:type rdf:resource="http://xmlns.com/foaf/0.1/Document"/>
	<title xmlns="http://purl.org/dc/elements/1.1/">Grapple Project</title>
	<description xmlns="http://purl.org/dc/elements/1.1/">The Website of the Grapple Project</description>
	<seeAlso xmlns="http://www.w3.org/2000/01/rdf-schema#" rdf:resource="http://www.grapple-project.org"/>
	<tags:taggedWithTag rdf:resource="http://groupme.org/GroupMe/tag/grapple"/>
	<tags:taggedWithTag rdf:resource="http://groupme.org/GroupMe/tag/project"/>
</rdf:Description>

<rdf:Description rdf:about="http://groupme.org/GroupMe/tag/grapple">
	<rdf:type rdf:resource="http://www.holygoat.co.uk/owl/redwood/0.1/tags/#Tag"/>
	<tags:name>grappleg</tags:name>
</rdf:Description>

<rdf:Description rdf:about="http://groupme.org/GroupMe/tag/project">
	<rdf:type rdf:resource="http://www.holygoat.co.uk/owl/redwood/0.1/tags/#Tag"/>
	<tags:name>project</tags:name>
</rdf:Description>

</rdf:RDF>

In the example, the resource (http://groupme.org/GroupMe/resource/id-not-yet-set), which actually is a bookmark of the Web site http://www.grapple-project.org, will be added to the group http://groupme.org/GroupMe/group/1508 if the client application (groupmewebclient) is authorized, i.e. if the oauth_token is valid. If the resource was added successfully then the entire group (i.e. http://groupme.org/GroupMe/group/1508), to which the resource was added, will be returned: 


<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
	xmlns:gm="http://groupme.org/rdf/groupme.owl#"
	xmlns:dc="dc"
	xmlns:foaf="http://xmlns.com/foaf/0.1/"
	xmlns:tags="http://www.holygoat.co.uk/owl/redwood/0.1/tags/#"
	xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">

<Group rdf:about="http://groupme.org/GroupMe/group/1508">
	<dc:title>Grapple Kickoff Meeting - Eindhoven</dc:title>
    <dc:description>GRAPPLE is an EU FP7 STREP Project which deals with design, developement, 
    and evaluation of Generic Responsive Adaptive Personalized Learning Environment, ...
    </dc:description>
      
	<contains> 
		<foaf:Document rdf:about="http://groupme.org/GroupMe/resource/1509">
			<rdfs:seeAlso rdf:resource="http://semweb.kbs.uni-hannover.de/blogging/rss.xml"/>
		</foaf:Document>
	</contains>
	  
	<contains> 
		<foaf:Document rdf:about="http://groupme.org/GroupMe/resource/1510">
			<rdfs:seeAlso rdf:resource="http://www.grapple-project.org"/>
		</foaf:Document>
	</contains>
	  
	<contains> 
		<foaf:Document rdf:about="http://groupme.org/GroupMe/resource/1511">
			<rdfs:seeAlso rdf:resource="http://static.flickr.com/111/312822374_fa659bf0e7.jpg"/>
		</foaf:Document>
	</contains>
	  
	<contains> 
		<foaf:Document rdf:about="http://groupme.org/GroupMe/resource/1512">
			<rdfs:seeAlso rdf:resource="http://static.flickr.com/254/451363397_a68c8e6f5a.jpg"/>
		</foaf:Document>
	</contains>
	  
	<foaf:maker>
		<foaf:Person rdf:about="http://groupme.org/GroupMe/user/fabian">
			<foaf:name>Fabian Abel</foaf:name>
			<foaf:img rdf:resource="http://www.l3s.de/~abel/fob.jpg"/>
		  	<rdfs:seeAlso rdf:resource="http://www.l3s.de/~abel/foaf.rdf"/>
		</foaf:Person>
	</foaf:maker>
	  
  	<tags:taggedWithTag>
 		<tags:Tag rdf:about="http://groupme.org/GroupMe/tag/grapple">
		<tags:name>grapple</tags:name>
  		</tags:Tag>
  	</tags:taggedWithTag>
  
  	<tags:taggedWithTag>
  		<tags:Tag rdf:about="http://groupme.org/GroupMe/tag/eindhoven">
  			<tags:name>eindhoven</tags:name>
  		</tags:Tag>
  	</tags:taggedWithTag>
  </Group>
</rdf:RDF>

Hence, only the ID of the bookmark that was added (http://groupme.org/GroupMe/resource/1510) as well as the original URL (http://www.grapple-project.org) are contained in the response. Further details about the resource can be accessed by performing a GET request: http://groupme.org/GroupMe/resource/1510.