Concept Space Interchange Protocol Documentation
Faisal Ahmad - Boulder Learning Technologies Lab (BoLT), University of Colorado at Boulder.
The Concept Space Interchange Protocol (CSIP) provides programmatic access to the concept map repository. The service provides a rich search API and gives full access to the concept map metadata. Developers can use the CSIP to dynamically generate concept maps, fragment of concept maps and search digital library resources supporting concept maps. The service supports textual as well as navigational searching over the concept maps. Developers can use features of textual search to search appropriate concepts, list of concepts, concept maps and concept maps fragments. The navigational search allows for searching using relationships between concepts e.g. what is the pre-requisite to a given concept. The concept maps can be access in a number of formats e.g. XML, OWLLite, SVG, PDF, PNG, TIFF, and JPEG.
Currently, the service contains maps from the Atlas of Science Literacy published by the American Association for the Advencement of Science (AAAS), Project 2061.
You can browse these concept maps, or benchmarks, here.
Additional concept maps will be added to the service in the future.
The Web service requests and responses are described in detail below and examples are provided for reference by developers.
Thanks to Tammy Sumner, Greg Janee, Mike Wright, John Weatherley, Sonal Bhushan, Sebastian de la Chica, Qianyi Gu and other BoLT, DLESE, AAAS Project 2061 and ADEPT collaborators who contributed directly or indirectly to the design and testing of this service. The design of this service was greatly informed by the work of the Alexandria Digital Library Gazetteet Protocol and DLESE Search Web Service.
Definitions and concepts
CSIP is a REpresentational State Transfer (REST) style Web service. In REST style Web service architectures, requests are typically encoded as a URL and responses are returned as XML. This is the case with CSIP.
More formally: CSIP requests are expressed as HTTP argument/value pairs. These requests must be in either GET or POST format. Responses are returned in XML format, which varies in structure and content depending on the request.
- Base URL - the base URL used to access the Web service. This is the portion of the request that precedes the request arguments. For example http://strandmaps.nsdl.org/cms1-2.
- Request arguments - the argument=value pairs that make up the request and follow the base URL.
- CSIP response envelope - the XML container used to return data. This container returns different types of data depending on the request made.
HTTP request formats
CSIP request can be made by using three different HTTP formats:
- HTTP GET Method - This request format consists of the base URL followed by the one of the service requests literal. Some of the service request literals are followed by ? character which is appended with key=value pairs. If more than one key value pairs are required by the service request then the key=value pairs are concatenated by an & symbol.
- HTTP POST Method 1 - This request format consists of the base URL followed by the one of the service requests literal. The key=value pairs are embedded in the body of the request
- HTTP POST Method 2 - This request format consists of the base URL followed by the one of the service requests literal. No key=value pair is used in this kind of request but the value is directly embedded in the request.
CSIP requests and responses
This section defines the available requests.
The HTTP request format has the following canonical structure: [base URL]/request.
For example:
http://strandmaps.nsdl.org/cms1-2/ServiceDescription
Summary of available requests:
ServiceDescription - Retrieves the capabilities of CSIP server and along with the version number.
SubmitResource - Allow clients to submit a examplary resources useful for teaching and learning a concept in the concept map repository.
RegisterQuery - Enable clients to associate search query strings with concepts.
Query - Allows a client to search through concept maps and reterieve the matching concept maps in a number of formats.
ServiceDescription
Sample request
The following request get the CSIP server capabalities and version information:
http://strandmaps.nsdl.org/cms1-2/ServiceDescription
Summary and usage
This request allows a clinet to determine the capabilities of the CSIP server. Clients can dynamic discovery available features of a CSIP server and tailor their behavior accordingly. This service request is also useful in a client is dealing with multiple CSIP servers which have varying capabilities.
Arguments
This service request does not take any arguments.
Errors and exceptions
Error will only be reported if the literal is not spelled correctly.
Examples
Request
Get the CSIP server capabilities
http://strandmaps.nsdl.org/cms1-2/ServiceDescription
Response
<SMS-CSIP> <ServiceDescriptionResponse> <Version majorNo="1" minorNo="0">Concept Map Service Server</Version> <SupportedConfigurations> <Configuration>Skeleton</Configuration> <Configuration>Detailed</Configuration> </SupportedConfigurations> <SupportedQueryTypes> <Query>Content-Query</Query> <Query>Navigational-Query</Query> </SupportedQueryTypes> <SupportedOperators> <Operator>Logical</Operator> <Operator>Relational</Operator> </SupportedOperators> <SupportedReplyFormats> <Format>SMS</Format> <Format>SMS-JSON</Format> <Format>SVG</Format> <Format>SVG-JSON</Format> <Format>JPEG</Format> <Format>PNG</Format> <Format>TIFF</Format> <Format>PDF</Format> <Format>OWLLite</Format> </SupportedReplyFormats> <SupportedLibrarySearch> <Library>Google XML</Library> <Library>DLESE</Library> <Library>NSDL XML</Library> <Library>Harvard Smithsonian</Library> <Library>DLESE XML</Library> </SupportedLibrarySearch> <SupportedExtensions/> </ServiceDescriptionResponse> </SMS-CSIP> |
SubmitResource
Sample request
The following request sends an email to the AAAS personnel suggesting an examplary resource for teaching a concept:
http://strandmaps.nsdl.org/cms1-2/SubmitResource?ObjectID=SMS-BMK-1201&Resource=http://www.usd.edu/esci/exams/earthquakes.html&email=fahmad@colorado.edu
Summary and usage
The SubmitResource request can be used by clients to contribute examplary resources. These examplary resources will become available to a wide range of digital libraries using the CSIP web-service.
Arguments
- ObjectID - A mandatory argument that should contain the value of CSIP identifier in appropriate format.
- Resource - A mandatory argument that should contain the URL of the web-resource.
- email - A mandatory argument that specifies clients email address.
Errors and exceptions
Error is indicted if the request does not have the mandatory arguments or ObjectID does not follow the CSIP format.
Examples
Request
Submit an examplary resource for ingestion into CSIP
http://strandmaps.nsdl.org/cms1-2/SubmitResource?ObjectID=SMS-MAP-1200&Resource=http://soils.ag.uidaho.edu/soilorders/index.htm&email=fahmad@colorado.edu
Response
A confirmation email is sent to the client.
RegisterQuery
Sample request
The following request registers a digital library query with CSIP using HTTP GET method:
http://strandmaps.nsdl.org/cms1-2/RegisterQuery?RegisterQuery=<SMS-CSIP xmlns="http://sms.dlese.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<RegisterQuery CharacterEncoding="UTF-8">
<Functional>
<Operation>Add Query String</Operation>
<PublishName>SAMPLE-TEST</PublishName>
<AuthenticationCode>Hello World</AuthenticationCode>
<QueryString>s<Group Repeat=" OR ">\"<Subjects Delimiter=" " Paran="false"></Subjects>\"</Group> <Group Repeat=" ">\"<Keywords Delimiter=" " Paran="false"></Keywords>\"</Group></QueryString>
<ObjectType>Benchmark</ObjectType>
</Functional>
</RegisterQuery>
</SMS-CSIP>
The above mentioned request can also be made using HTTP POST method in two ways:
- Using a key=value pair - The key should be RegisterQuery and value will be the above mentioned XML fragment.
- Without using a key=value pair - In this senario the above mentioned XML fragment can be directly included in the body of post method request.
Summary and usage
The RegisterQuery request can be used by clients to register custom queries to a concept, lookup already registered queries, update an already registered query, and search for registered queries. When registering a query the client specifies a meta-query which get expanded when the concept map is returned to the client. The meta-query specifies query expansion rules using data from the concept map metadata.
Schema
The schema gives the rules for constructing the RegisterQuery request. Click here to see RegisterQuery schema type
Arguments
- RegisterQuery - If using HTTP GET this key is mandatory. For HTTP POST method this key is optional.
Register Query Options
- SeeAllQueries - A client can get the list of registered queries using this option
- Lookup - A clinet can search for a query already registered
- Functional - This operation can be used by a client to add a new query string or update a previsouly added query string.
- Authentication - This operation is used to change password of a registered query.
- Admin - A client can use this option to delete, enable and disable a registered query
Examples
| 1. |
|
||||||||
| 2. |
|
||||||||
| 3. |
| ||||||||
| 4. |
| ||||||||
| 5. |
|
||||||||
Errors and exceptions
Error is indicted if the request does not conform to RegisterQuery schema.
Query
Sample request
The following request send a query to searh for concept maps in the repository:
http://strandmaps.nsdl.org/cms1-2/Query?Query=<SMS-CSIP xmlns="http://sms.dlese.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><Query><Content-Query><Term>Ocean floor</Term></Content-Query></Query></SMS-CSIP>
The above mentioned request can also be made using HTTP POST method in two ways:
- Using a key=value pair - The key should be Query and value will be the above mentioned XML fragment.
- Without using a key=value pair - In this senario the above mentioned XML fragment can be directly included in the body of post method request.
Summary and usage
The Query request can be used by clients to search through concept maps and retrieve concept maps in different formats.
Schema
The schema gives the rules for constructing the Query request. Click here to see Query schema type
Arguments
- Query - If using HTTP GET this key is mandatory. For HTTP POST method this key is optional.
Query Options
- Content-Query - A client can use this query type to search through the concept map metadata.
- Navigational-Query - A client can use this query type to look for concepts that are related to other concepts.
Query Element Attributes
- Color - Color of the concept nodes in graphical representation of concept map. The default value is skyblue. This attribute is only useful when the response format request is SVG, PNG, TIFF, or JPEG.
-
DetailLevel - Using this attribute a client can decide on amount of metadata retrieved for a concept. This attribute is only useful if the response type is either SMS or OWLLite. This attribute can take two values:
- Skeleton (default)
- Detailed
-
Format - The response format for concept maps. It can take following values:
- SMS (Default)
- SMS-JSON
- SVG
- SVG-JSON
- JPEG
- TIFF
- PNG
- OWLLite
-
Scope - It can be used to optimize the query search performance. Given an object type in scope, the search will restrict itself to just that object type and will not look into other object types. Following scope values are possible:
- ALL (Default)
- Atlas
- Benchmark
- Chapter
- Cluster
- Grade group
- Map
- Science for all americans paragraph
- Section
- Strand
- ThirdPartyQuery - Using this attribute a client can get a query string for some digital library for a concept. To get a query string the value must match some registered query published name.
- ImageScale - Scale of the returned map image if graphical format other than SVG is used. Its value can range between 1-200 (1 percent to 200 percent)
- ConceptSize - Size of the concept boxes. Its value can range between 1-6, i being the smallest and 6 being the largest.
Examples
| 1. |
|
||||||||
| 2. |
|
||||||||
| 3. |
|
||||||||
| 4. |
|
||||||||
| 5. |
|
||||||||
| 6. |
|
||||||||
| 7. |
|
||||||||
|
For detials about how to formulate queries please refer to Concept Space Interchange Protocol schema. |
|||||||||
CSIP identifier format
According to Concept Space Interchange Protocol the CSIP identifier should followinw the following pattern: [Three letters]-[three letters]-[4 digits] e.g. SMS-CHP-1526
CSIP Object Hierarchy
 |