Web services (deprecated as of v1.3)

From CollectiveAccess Documentation
(Redirected from Web services)
Jump to: navigation, search

Note: the web service layer described here has been deprecated as of v1.3 and replaced with a new, simplified Web Service API

General

CollectiveAccess supports a broad range of its functionality through a number of web services that can be accessed by other software, developed in any programming language you like. The web services are divided into 5 groups:

  • Cataloguing - changing data
  • ItemInfo - getting detailed info on an object, entity, occurrence, etc.
  • UserContent - creating and viewing user-contributed content like comments, ratings, tags and sets
  • Search - searching the dataset using the CollectiveAccess search engine (and its syntax)

All functions of these 3 service groups can be accessed using either the Simple Object Access Protocol (SOAP) or through RESTful URLs. CollectiveAccess also provides services definitions in WSDL format for the SOAP services. Most client libraries allow you to feed them with a WSDL file and provide convenient functions based upon that (e.g. the client that ships with the PHP SOAP extension: SoapClient).

API Consistency

Please also note that the SOAP and REST service APIs use the same PHP code as basis to provide the service. This means that the function names, parameter names, parameter types and return types are exactly the same. Hence, you can use the WSDL to inspect the service structure even if you plan to use the RESTful approach. Since the BrowseEngine wrapper requires lots of state information we don't provide a RESTful service for this category.

Notation

From now on the following notation will be used to denote URLs that access a resource provided by a CollectiveAccess instance: The URL root will be an empty string, the hostname will be "localhost" and the protocol will be "http". You will have to adapt these to match your setup if you want to use any of them. For instance, here is the URL to the CollectivAccess index.php

http://localhost/index.php

Web service definitions

Cataloguing: http://localhost/service.php/cataloguing/Cataloguing/soapWSDL
ItemInfo: http://localhost/service.php/iteminfo/ItemInfo/soapWSDL
UserContent: http://localhost/service.php/usercontent/UserContent/soapWSDL
Search: http://localhost/service.php/search/Search/soapWSDL
Browse: http://localhost/service.php/browse/Browse/soapWSDL

Representational State Transfer

As noted above, the methods for the REST services are identical to the SOAP methods but of course you need to know how to call them. Since we use the Zend_Rest_Server package that ships with Zend the format is the following:

http://localhost/service.php/<module>/<service>/<action>?method=<methodName>&<arg1>=<argv1>&<arg2>=<argv2>&<arg3>=<arg3>

The avalable module-service-action combinations will be listed below, as well as available methods and their arguments. What you get back if you call these methods is the Zend framwork conversion of trvial and complex (we don't use anything more "complex" than associative arrays) PHP types to ad-hoc XML, which is very easy to understand and which should be easy to handle as well.

Please note that the methods of the Browse service are not available via REST.

Service API

Please note that all parameters have a leading $ character since the method list was generated using PHPDocumentor. This character is of course absent in the real service parameter names.

Also the simple method lists below and the library documentation generated by phpdoc lack detailed descriptions of the return formats, so for now you will have to figure that out for yourself by inspecting example return values. However, the formats are all very CA-ish (i.e. similar to the corresponding PHP library function return formats) and (kind of) consistent.

Also note that all services feature the additional methods

int  auth  ([string $username  = ""], [string $password = ""])
boolean deauthenticate ()
int  getUserID  () 

Depending on the settings in the access restrictions configuration file the service may require you to log in with a username and password. It may also restrict access if you don't have the required privileges. The auth() method returns your user identifier (a non-zero value if the login was successful). You can also get your user identifier using the getUserID method to see if your session is still alive.

Cataloguing

The SOAP service URL for this URL is stated below. However, before you use that directly you should check if your SOAP library supports initialization via WSDLs. If that is possible you should use the WSDL URL from section 2.

http://localhost/service.php/cataloguing/Cataloguing/soap

The corresponding REST service can be found at:

http://localhost/service.php/cataloguing/Cataloguing/rest

The services serve the methods below. If you are familiar with CollectiveAccess-related development the parameter names will probably be enough for you to get started. If not, please have a look at the more detailed class documentation here.

int  add  (string $type, array $fieldInfo)
boolean addAttribute (string $type, int $item_id, string $attribute_code_or_id, array $attribute_data_array)
boolean addAttributes (string $type, int $item_id, array $attribute_list_array)
int addLabel (string $type, int $item_id, array $label_data_array,  $localeID, boolean $is_preferred)
bool addObjectRepresentation (int $object_id, string $media_url, int $type_id, int $locale_id, int $status, int $access, int $is_primary)
boolean addRelationship (string $type, int $item_id, string $related_type, int $related_item_id, int $relationship_type_id, string $source_info)
int auth (string $username, string $password)
boolean editAttribute(string $type, int $item_id, int $attribute_id, string $attribute_code_or_id, array $attribute_data_array)
int editLabel(string $type, int $item_id, int $label_id, array $label_data_array, int $localeID, boolean $is_preferred)
boolean remove (string $type, int $item_id)
boolean removeAllAttributes (string $type, int $item_id)
boolean removeAllLabels (string $type, int $item_id)
boolean removeAttribute (string $type, int $item_id, int $attribute_id)
boolean removeLabel (string $type, int $item_id, int $label_id)
boolean removeObjectRepresentation (int $representation_id)
boolean removeRelationship (string $type, string $related_type, int $relation_id)
boolean replaceAttribute (string $type, int $item_id, string $attribute_code_or_id, array $attribute_data_array)
boolean update (string $type, int $item_id, array $fieldInfo)
boolean updateAttributes (string $type, int $item_id, array $attribute_list_array)
boolean updateRelationship (string $type, string $related_type, int $relation_id, int $relationship_type_id, string $source_info) 

ItemInfo

The SOAP service URL for this URL is stated below. However, before you use that directly you should check if your SOAP library supports initialization via WSDLs. If that is possible you should use the WSDL URL from section 2.

http://localhost/service.php/iteminfo/ItemInfo/soap

The corresponding REST service can be found at:

http://localhost/service.php/iteminfo/ItemInfo/rest

The services serve the methods below. If you are familiar with CollectiveAccess-related development the parameter names will probably be enough for you to get started. If not, please have a look at the more detailed class documentation here.

int  auth  (string $username, string $password)
array get(string $type, int $item_id, array $bundles, array $options)
array getAttributes (string $type, int $item_id)
array getAttributesByElement (string $type, int $item_id, string $attribute_code_or_id)
array getApplicableElementCodes (string $type, int $type_id, boolean $include_sub_element_codes)
array getItem (string $type, int $item_id)
array getLabels (string $type, int $item_id, string $mode)
array getObjectRepresentations (int $object_id, array $versions)
array getPrimaryObjectRepresentation (int $object_id, array $versions)
array getRelationships (string $type, int $item_id, string $related_type)
array getRelationshipTypes (string $type, int $sub_type_id, string $related_type, int $related_sub_type_id)
array getSets()
array getSet (int $set_id)
array getSetItems (int $set_id, array $options)
array getSetsForItem (string $type, int $item_id)
array getLastChangedItems(string $type, int $timestamp)

UserContent

The SOAP service URL for this URL is stated below. However, before you use that directly you should check if your SOAP library supports initialization via WSDLs. If that is possible you should use the WSDL URL from section 2.

http://localhost/service.php/usercontent/UserContent/soap

The corresponding REST service can be found at:

http://localhost/service.php/usercontent/UserContent/rest

The services serve the methods below. If you are familiar with CollectiveAccess-related development the parameter names will probably be enough for you to get started. If not, please have a look at the more detailed class documentation here.

boolean  addComment  (string $type, int $item_id, array $comment_info_array)
int addItemToSet (int $set_id, string $type, int $item_id, array $set_item_info_array)
int addSet (string $type, array $set_info_array)
boolean addTag (string $type, int $item_id, array $tag_info_array)
int auth (string $username, string $password)
array getComments (string $type, int $item_id)
array getTags (string $type, int $item_id)
boolean removeItemFromSet (int $set_id, int $set_item_id)
boolean removeSet (int $set_id)
boolean updateSet (int $set_id, array $set_info_array)
boolean updateSetItem (int $set_item_id, array $set_item_info_array)

Search

The SOAP service URL for this URL is stated below. However, before you use that directly you should check if your SOAP library supports initialization via WSDLs. If that is possible you should use the WSDL URL from section 2.

http://localhost/service.php/search/Search/soap

The corresponding REST service can be found at:

http://localhost/service.php/search/Search/rest

The services serve the method below. If you are familiar with CollectiveAccess-related development the parameter names will probably be enough for you to get started. If not, please have a look at the more detailed class documentation here. Please note that you cannot use the queryRest() method via SOAP. The service will return an invalid SOAP response. If you're building service clients with SOAP, use the querySoap() method.

DOMDocument queryRest(string $type, string $query)
array querySoap(string $type, string $query)

Examples

A very basic example script (written in PHP) that performs some common tasks using the above services can be found in svn (location noted below). Looking at the source code of this script may help you to get started with your own client applications.

trunk/support/utils/other/exampleServiceClient.php

i_sphinx

Namespaces

Variants
Actions
Navigation
Tools
User
Personal tools