BRestful Class Reference

The BRestful class. More...

#include <btrieveCpp.h>

Static Public Member Functions
static const char *	DELETE (const char *collectionName, int id=-1, int entityTag=-1)
	Delete a collection or document.
static const char *	GET (const char *collectionName, const char *query=NULL)
	Retrieve document identifiers.
static const char *	GET (const char *collectionName, int id)
	Retrieve a document.
static const char *	GET (const char *collectionName, int id, char *blob, int blobSize, int documentBlobOffset=0, int documentBlobLength=0)
	Retrieve a document.
static const char *	POST (const char *collectionName, const char *json, const char *blob, int blobLength)
	Create a collection or document.
static const char *	POST (const char *collectionName, const char *json=NULL)
	Create a collection or document.
static const char *	PUT (const char *collectionName, int id, const char *json)
	Update a document.
static const char *	PUT (const char *collectionName, int id, const char *json, const char *blob, int blobLength)
	Update a document.
static const char *	PUT (const char *collectionName, int id, int entityTag, const char *json)
	Update a document.
static const char *	PUT (const char *collectionName, int id, int entityTag, const char *json, const char *blob, int blobLength)
	Update a document.

Detailed Description

The BRestful class.

Note

This class is currently a beta release; feedback about usage and suggestions for improvements are requested, and can be submitted at https://communities.actian.com/s/actian-zen.

The BRestful class is targeted at RESTful HTTP API developers. To that end a subset of the HTTP methods is supported. These methods are DELETE, GET, POST and PUT.

HTTP Method	BRestful Method	Description	Required Parameters	Optional Parameters	Returns
DELETE	BRestful::DELETE	Delete a collection	Collection name		Status
DELETE	BRestful::DELETE	Delete a document	Collection name and document identifier	Entity tag	Status
GET	BRestful::GET	Query a collection	Collection name	Query	Status and array of document identifiers
GET	BRestful::GET	Retrieve a document	Collection name and document identifier	User BLOB buffer	Status, entity tag, document JSON, and optional document BLOB
POST	BRestful::POST	Create a collection	Collection name		Status
POST	BRestful::POST	Create a document	Collection name and document JSON content	Document BLOB content	Status, document identifier and entity tag
PUT	BRestful::PUT	Update a document	Collection name and document identifier	Entity tag, Document JSON and BLOB content	Status and entity tag

All methods return JSON. In addition to the reserved JSON field names listed in BtrieveCollection the following reserved JSON field names are defined:

Field Name	User Settable	Type	Description
_collectionName	no	string	The collection name.
_entityTag	no	number	The entity tag.
_ids	no	array of numbers	An array of document identifiers.
_statusCode	no	number	The status code.
_statusString	no	string	The status string.

Non-user settable JSON field names are silently ignored by BRestful::GET, BRestful::POST, and BRestful::PUT. Use of reserved JSON field names other than those listed both above and in BtrieveCollection will generate an error.

See also

BtrieveCollection

Member Function Documentation

DELETE()

static const char * BRestful::DELETE ( const char * collectionName, int id = -1, int entityTag = -1 )

static

Delete a collection or document.

Note

This method is not thread safe. The string returned will be overwritten on subsequent calls.

Parameters

[in]	collectionName	The collection name.
[in]	id	The identifier. If identifier is not given or is -1, then a collection will be deleted.
[in]	entityTag	The entity tag. The entity tag must either equal the entity tag of the document or -1.

Snippet

Python brestful.py

response = json.loads(btrievePython.BRestful.DELETE(collectionName))
assert(response["_statusCode"] == btrievePython.Btrieve.STATUS_CODE_NO_ERROR), response["_statusString"]

Returns

{ 
   "_collectionName" : <collectionName>, 
   "_statusCode" : 0, 
   "_statusString" : "No error" 
}

Success. A collection was deleted.

{ 
   "_collectionName" : <collectionName>, 
   "_entityTag": <entityTag>,
   "_id" : <id>, 
   "_statusCode" : 0, 
   "_statusString" : "No error" 
}

Success. A document was deleted.

{ 
   "_statusCode" : <statusCode>, 
   "_statusString" : <statusString>
} 

An error has occurred.

See also

BtrieveClient::CollectionDelete BtrieveCollection::DocumentDelete Btrieve::StatusCode Btrieve::StatusCodeToString

GET() [1/3]

static const char * BRestful::GET ( const char * collectionName, const char * query = NULL )

static

Retrieve document identifiers.

Note

This method is not thread safe. The string returned will be overwritten on subsequent calls.

Parameters

[in]	collectionName	The collection name.
[in]	query	The query.

Snippet

Python brestful.py

response = json.loads(btrievePython.BRestful.GET(collectionName, query))
assert(response["_statusCode"] == btrievePython.Btrieve.STATUS_CODE_NO_ERROR), response["_statusString"]

Returns

{ 
   "_collectionName" : <collectionName>, 
   "_ids" : [ <id> ... ], 
   "_statusCode" : 0, 
   "_statusString" : "No error" 
}

Success.

{ 
   "_statusCode" : <statusCode>, 
   "_statusString" : <statusString>
} 

An error has occurred.

See also

BtrieveCollection::Query Btrieve::StatusCode Btrieve::StatusCodeToString

GET() [2/3]

static const char * BRestful::GET ( const char * collectionName, int id )

static

Retrieve a document.

Note

This method is not thread safe. The string returned will be overwritten on subsequent calls.

Parameters

[in]	collectionName	The collection name.
[in]	id	The identifier.

Snippet

Python brestful.py

response = json.loads(btrievePython.BRestful.GET(collectionName, documentId))
assert(response["_statusCode"] == btrievePython.Btrieve.STATUS_CODE_NO_ERROR), response["_statusString"]

Returns

{ 
   <documentJson>, 
   "_collectionName" : <collectionName>, 
   "_entityTag": <entityTag>,
   "_statusCode" : 0, 
   "_statusString" : No error,
}

Success.

{ 
   "_statusCode" : <statusCode>, 
   "_statusString" : <statusString>
} 

An error has occurred.

See also

BtrieveCollection::DocumentRetrieve Btrieve::StatusCode Btrieve::StatusCodeToString

GET() [3/3]

static const char * BRestful::GET ( const char * collectionName, int id, char * blob, int blobSize, int documentBlobOffset = 0, int documentBlobLength = 0 )

static

Retrieve a document.

Note

This method is not thread safe. The string returned will be overwritten on subsequent calls.

Parameters

[in]	collectionName	The collection name.
[in]	id	The identifier.
[out]	blob	The blob.
[in]	blobSize	The blob size.
[in]	documentBlobOffset	The document blob offset.
[in]	documentBlobLength	The document blob length.

Returns

{ 
   <documentJson>, 
   "_collectionName" : <collectionName>, 
   "_entityTag": <entityTag>,
   "_statusCode" : 0, 
   "_statusString" : No error,
}

Success.

{ 
   "_statusCode" : <statusCode>, 
   "_statusString" : <statusString>
} 

An error has occurred.

See also

BtrieveCollection::DocumentRetrieve Btrieve::StatusCode Btrieve::StatusCodeToString

POST() [1/2]

static const char * BRestful::POST ( const char * collectionName, const char * json, const char * blob, int blobLength )

static

Create a collection or document.

Note

This method is not thread safe. The string returned will be overwritten on subsequent calls.

Parameters

[in]	collectionName	The collection name.
[in]	json	The json. If json is NULL, then a collection will be created.
[in]	blob	The blob. If json is NULL, then blob and blobLength are ignored.
[in]	blobLength	The blob length.

Description

Creating a collection will not overwrite an existing collection. The existing collection must be deleted first. See BRestful::DELETE.

Creating a document requires that the containing collection exist first.

Returns

{ 
   "_collectionName" : <collectionName>, 
   "_statusCode" : 0, 
   "_statusString" : "No error"
} 

Success. A collection was created.

{ 
   "_collectionName" : <collectionName>, 
   "_entityTag": <entityTag>,
   "_id" : <id>, 
   "_statusCode" : 0, 
   "_statusString" : "No error" 
} 

Success. A document was created.

{ 
   "_statusCode" : <statusCode>, 
   "_statusString" : <statusString>
} 

An error has occurred.

See also

BtrieveClient::CollectionCreate BtrieveCollection::DocumentCreate Btrieve::StatusCode Btrieve::StatusCodeToString

POST() [2/2]

static const char * BRestful::POST ( const char * collectionName, const char * json = NULL )

static

Create a collection or document.

Note

This method is not thread safe. The string returned will be overwritten on subsequent calls.

Parameters

[in]	collectionName	The collection name.
[in]	json	The json. If json is not given or is NULL, then a collection will be created.

Description

Creating a collection will not overwrite an existing collection. The existing collection must be deleted first. See BRestful::DELETE.

Creating a document requires that the containing collection exist first.

Snippet

Python brestful.py

response = json.loads(btrievePython.BRestful.POST(collectionName))
assert(response["_statusCode"] == btrievePython.Btrieve.STATUS_CODE_NO_ERROR), response["_statusString"]

Snippet

Python brestful.py

    response = json.loads(btrievePython.BRestful.POST(collectionName, documentJson))
    assert(response["_statusCode"] == btrievePython.Btrieve.STATUS_CODE_NO_ERROR), response["_statusString"]

Returns

{ 
   "_collectionName" : <collectionName>, 
   "_statusCode" : 0, 
   "_statusString" : "No error"
} 

Success. A collection was created.

{ 
   "_collectionName" : <collectionName>, 
   "_entityTag": <entityTag>,
   "_id" : <id>, 
   "_statusCode" : 0, 
   "_statusString" : "No error" 
} 

Success. A document was created.

{ 
   "_statusCode" : <statusCode>, 
   "_statusString" : <statusString>
} 

An error has occurred.

See also

BtrieveClient::CollectionCreate BtrieveCollection::DocumentCreate Btrieve::StatusCode Btrieve::StatusCodeToString

PUT() [1/4]

static const char * BRestful::PUT ( const char * collectionName, int id, const char * json )

static

Update a document.

Note

This method is not thread safe. The string returned will be overwritten on subsequent calls.

Parameters

[in]	collectionName	The collection name.
[in]	id	The identifier.
[in]	json	The json.

Returns

{ 
   "_collectionName" : <collectionName>, 
   "_entityTag": <entityTag>,
   "_id" : <id>, 
   "_statusCode" : 0, 
   "_statusString" : "No error" 
}

Success.

{ 
   "_statusCode" : <statusCode>, 
   "_statusString" : <statusString>
} 

An error has occurred.

See also

BtrieveCollection::DocumentUpdate Btrieve::StatusCode Btrieve::StatusCodeToString

PUT() [2/4]

static const char * BRestful::PUT ( const char * collectionName, int id, const char * json, const char * blob, int blobLength )

static

Update a document.

Note

This method is not thread safe. The string returned will be overwritten on subsequent calls.

Parameters

[in]	collectionName	The collection name.
[in]	id	The identifier.
[in]	json	The json.
[in]	blob	The blob.
[in]	blobLength	The blob length.

Returns

{ 
   "_collectionName" : <collectionName>, 
   "_entityTag": <entityTag>,
   "_id" : <id>, 
   "_statusCode" : 0, 
   "_statusString" : "No error" 
}

Success.

{ 
   "_statusCode" : <statusCode>, 
   "_statusString" : <statusString>
} 

An error has occurred.

See also

BtrieveCollection::DocumentUpdate Btrieve::StatusCode Btrieve::StatusCodeToString

PUT() [3/4]

static const char * BRestful::PUT ( const char * collectionName, int id, int entityTag, const char * json )

static

Update a document.

Note

This method is not thread safe. The string returned will be overwritten on subsequent calls.

Parameters

[in]	collectionName	The collection name.
[in]	id	The identifier.
[in]	entityTag	The entity tag. The entity tag must either equal the entity tag of the document or -1.
[in]	json	The json.

Returns

{ 
   "_collectionName" : <collectionName>, 
   "_entityTag": <entityTag>,
   "_id" : <id>, 
   "_statusCode" : 0, 
   "_statusString" : "No error" 
}

Success.

{ 
   "_statusCode" : <statusCode>, 
   "_statusString" : <statusString>
} 

An error has occurred.

See also

BtrieveCollection::DocumentUpdate Btrieve::StatusCode Btrieve::StatusCodeToString

PUT() [4/4]

static const char * BRestful::PUT ( const char * collectionName, int id, int entityTag, const char * json, const char * blob, int blobLength )

static

Update a document.

Note

This method is not thread safe. The string returned will be overwritten on subsequent calls.

Parameters

[in]	collectionName	The collection name.
[in]	id	The identifier.
[in]	entityTag	The entity tag. The entity tag must either equal the entity tag of the document or -1.
[in]	json	The json.
[in]	blob	The blob.
[in]	blobLength	The blob length.

Returns

{ 
   "_collectionName" : <collectionName>, 
   "_entityTag": <entityTag>,
   "_id" : <id>, 
   "_statusCode" : 0, 
   "_statusString" : "No error" 
}

Success.

{ 
   "_statusCode" : <statusCode>, 
   "_statusString" : <statusString>
} 

An error has occurred.

See also

BtrieveCollection::DocumentUpdate Btrieve::StatusCode Btrieve::StatusCodeToString