Back to Contents

Route Generic Pattern

Introduction

There is a generic pattern for most resources accessible by Zafiro RESTful API. This is an example using the "wells" resource:

HTTP Verb	Path	Action	Used for
GET	/rest1/entity/wells	index	returns a list of all wells
POST	/rest1/entity/wells	create	create a new well
GET	/rest1/entity/wells/:id	read	returns the well with the argument :id
PUT	/rest1/entity/wells/:id	update	update the well with the argument :id
DELETE	/rest1/entity/wells/:id	delete	delete the well with the argument :id

This can be simplified to this pattern:

Partial-reads

Partial reads allows you to specify the contents of the resource you want to retrieve. You'll always get the resource ID, but you can also select which other fields you want to retrieve.

HTTP Verb	Path	Example	Used for
GET	/rest1/entity/wells/:id?fields=field1,field2,field3	/rest1/entity/wells/17?fields=name,startDate	returns the well with id 17, but with only its name and startDate
GET	/rest1/entity/wells/:id?fields=field1,field2.subField1	/rest/wells/17?fields=name,names.name2	returns the well with id 17, but with only its name and its names object name2.

Pagination (Allowed for index action only)

Pagination allows you to specify the amount of records to retrieve and the start offset on each request. The record index is 0 based so for the first record the offset is 0. The result set will contain all the records with index greater or equal than {offset} up to but not including {offset}+{limit} The default values offset is 0 and for limit is 25.

HTTP Verb	Path	Example	Used for
GET	/rest1/entity/wells/:id?offset={offsetValue}&limit={limitValue}	/rest1/entity/wells?offset=50&limit=25	returns the wells in the resultset from index 50 to 74 (included)

Ordering (Allowed for index action only)

Ordering allows you to specify the result set order. You can use it together with partial reads and specify the ordering for one or more fields including sort order (asc or desc) for each field.

HTTP Verb	Path	Example	Used for
GET	/rest1/entity/wells?sortBy={field1Name},{field2Name}	/rest1/entity/wells?sortBy=name,startDate	Returns the wells in the result set sorted by name and startdate. As sort order is not specified the default value ASC is used in all fields.
GET	/rest1/entity/wells?sortBy={field1Name},{field2Name}&sortOrder={field1SortOrder},{field2SortOrder}	/rest1/entity/wells?sortBy=name,startDate&sortOrder=asc,desc	Returns the wells in the result set sorted by name ASC and startdate DESC. The sortOrder parameter should contain the same number of elements than the sortBy argument.

Searching and Filtering (Allowed for index action only)

Searching allows you to find records in the result set using a matching criteria. You can specify several conditions:

Acronym	Description
lt	Lower
le	Lower or equal
gt	Greater
ge	Greater or equal
lk	Like (ignores case)
nl	Not Like (ignores case)
eq	Equals (case match)
ne	Not Equals (case match)
in	Included in (field values must be separated by exclamation marks "!")
ni	Not Included in (field values must be separated by exclamation marks "!")
nu	Is Nil (additional semicolon required ";". Example: ?q={fieldName};nu;;)
nn	Is Not Nil (additional semicolon required ";". Example: ?q={fieldName};nn;;)

HTTP Verb	Path	Example	Used for
GET	/rest1/entity/wells?q={fieldName};{acronym};{fieldValue}	/rest1/entity/wells?q=name;lk;AH-,startDate;lt;2013-01-01	returns the wells containing the "AH-" string anywhere in its name and with startDate lower than January 1th, 2013. Note the use of semicolon character in each search pattern group; each search pattern group should be separated by comma.

Zafiro Query Model (Allowed for index action only)

The Zafiro RESTful API implements Query Model processing capabilities. The Query Model API is alowed for the index action only. Included functionality are:

• Entity filtering
• Retrieval Strategy filtering
• Grouping (Not yet implemented)
• Aggregation (Not yet implemented)

Parameter	Description
rs	Retrieval Strategy Possible values: currents fromTo fromToWithCurrents
start	Start filtering operative date. Default value: today date
end	End filtering operative date Default value: same as start value
entities	Array of comma separated integers ID Default value: All entities

HTTP Verb	Path	Example	Used for
GET	/rest1/entity/productionWellTests?rs={rs option}	/rest1/entity/productionWellTests?rs=currents	Returns the productionWellTests records current at today for all wells in Zafiro database.
GET	/rest1/entity/productionWellTests?rs={rs option}&start={startDate}	/rest1/entity/productionWellTests?rs=currents&start=2013-01-01	Returns the productionWellTests records current at 2013-01-01 for all wells in Zafiro database.
GET	/rest1/entity/productionWellTests?rs={rs option}&start={startDate}&end={endDate}	/rest1/entity/productionWellTests?rs=fromto&start=2013-01-01&end=2013-01-31	Returns the productionWellTests records between 2013-01-01 and 2013-01-31 for all wells in Zafiro database.
GET	/rest1/entity/productionWellTests?rs={rs option}&start={startDate}&end={endDate}&entities={entityIds}	/rest1/entity/productionWellTests?rs=fromto&start=2013-01-01&end=2013-01-31&entities=1001,1002,1003	Returns the productionWellTests records between 2013-01-01 and 2013-01-31 for the wells with ID in (1001, 1002, 1003) from Zafiro database.