Skip to content
This repository has been archived by the owner on Nov 9, 2022. It is now read-only.

Home

Jump to bottom
isubiker edited this page Nov 12, 2011 · 131 revisions

API Documentation

Corona exposes a REST interface for storing, searching and transforming XML, JSON and text documents.

Inside each of the REST endpoints exists a number of other powerful features. For example, the entire structure of the documents can be queried with either key/value lookups, a search box query string, or a powerful structured query language. When retrieving documents, a path may be provided to extract out specific sections and XSLT transformations can be applied to the content.

Specific to JSON content, dates in dozens of formats can be parsed and stored as actual dates. If the value of a key is a string of XML, that XML can be unquoted, stored and queried as actual XML.

On top of this, you get the built in scalability, speed and database features that MarkLogic Server provides. Need geospatial support? It's included. Clustering? Yep, that's there too. Multiple languages? Of course! Powerful fulltext search? Nobody does it better.

NB: Corona is a community-sponsored project under active development. The endpoint APIs are still solidifying and are subject to change. This wiki documentation tracks the head revision of the master branch, which is what we suggest you do as well. We develop with automated tests, and we don't check in code until it passes all tests. Milestone bundles, for posterity, are available under the "Code" tab in the "Tags" area. You can "Watch" the project by clicking the button up above to have GitHub keep you informed of our progress.

Getting Started

Document Storage Endpoints

Documents are stored and indexed in the server. Each document has a unique uri where it is stored at. It can also be organized into multiple collections (think of them as having tags) and is automatically placed into a directory based off of its uri. Documents can also have external metadata called properties. To control access to the content, a sophisticated permissions system is available.

Transactions

By default a request to insert, update or delete a document executes in a single transaction. This means that a new transaction is created for each one of these requests. However, if multiple requests need to be grouped together and committed (or rolled back) at the same time, Corona supports this via the transaction endpoints.

Query Endpoints

Queries can be run over JSON or XML data, but not both in the same query.

  • Search Service - Search content in Corona via either string queries or structured queries
  • Key/Value Query Service - Convenient way to find documents via a simple key/value lookup
  • Facets - Build a faceted search interface by using this endpoint

Search Configuration Endpoints

These endpoints provide control over how Corona searches the content in the database. You can use them to enable various features in the string queries as well as structured queries.

  • Server Information - Current server configuration
  • Places - Tell Corona what keys, elements or attributes hold your textual content. Give a place a name for use in fielded queries.
  • Ranges - Configuring a range enables efficient queries over a range of values (e.g. eq, ne, lt, le, gt or ge) for a given key. Ranges are used for building [facets] and in queries where a comparison other than equals is required (eg: give me documents where the "price" is less than 50.00)
  • Bucketed Ranges - Bucketed ranges are similar to regular ranges, except that they allow values to be grouped together into "buckets" (eg: A-G, H-P, Q-Z)
  • Geo - Tell Corona what combination of keys, elements and attributes hold geospatial information
  • XML Namespace Definitions - Define prefixes for XML namespaces used in your content so it can be queried
  • Content Transformers - Mange XSLT transformations that can be used to modify the contents of a document before delivery

Miscellaneous

  • JSON Path - Describes our path syntax for accessing subsections of a JSON document
  • Simplified XPath - Describes our simplified XPath syntax for accessing subsections of a XML document
  • Extensions to JSON - Describes the conventions that we've implemented in JSON to support date and XML storage
  • XQuery API - Corona can be accessed via XQuery as well, for those that are MarkLogic experts
  • Error Codes - Describes the error codes found in responses

Meta

  • Credits - Who's doing all this work
  • Roadmap - Where the project is heading and what's left to be done
  • Performance - Various performance metrics
  • Versioning - Should URLs include the library version?
  • Test Coverage - High level notes on where we have test coverage
  • Term Glossary - Definition of some technical terms
Clone this wiki locally