Key Concepts

Formats (json, XML)

Two formats are supported with the REST APIs: json and xml. Each request must include the format in the query string of the url (the default format is xml, so technically it is only required for json requests).

http://restapi.lucity.net/gbaMS/Work/WorkOrders.svc/?format=json

Returns data in json

http://restapi.lucity.net/gbaMS/Work/WorkOrders.svc/?format=xml or

http://restapi.lucity.net/gbaMS/Work/WorkOrders.svc/

Returns data in xml.

For posting and putting (creating and updating) data, the format must be included both in the query string

http://restapi.lucity.net/gbaMS/Work/WorkOrders.svc/?format=json

And in the Content-Type of the request header. The content type for json is "application/json" or "text/javascript" and the content type for xml is "text/xml".

Special Requirements for XML

It is not necessary to include all properties on an object when posting. If you are using the Lucity serialization objects and serializing them that will just happen automatically, but if you are manually building XML it is perfectly acceptable to include just the properties you want to update or insert. For example, a request can be inserted with the following body:

Which will insert a new request with the problem code = test.

What is required, however, is that whatever properties are included are listed in alphabetical order. Again, if you are using the Lucity Serialization objects this is irrelevant.

Errors

The Lucity REST API tries to follow the HTTP standard for errors. The following is a table of errors that could be returned:

401 UNAUTHORIZED	The user likely did not provide credentials. The Lucity REST API will issue a challenge which will cause most browsers (if the client is a javascript client) to prompt for username and password. If you get this prompt, most likely you did not provide credentials or did not handle a 401 error from the client.
404 NOT FOUND	The requested record was not found or the client made a request to a URL that does not exist and should consult the help listing for available endpoints. For example http://restapi.lucity.net/gbaMS/Work/WorkOrders.svc/help contains the available endpoints for Work Orders.
400 BAD REQUEST	The client application requested something that the server considers invalid. This could be a problem in the formatting of the data sent to the server, it could be that the data sent to the server causes a rules violation (like an invalid problem code). 400 Errors will generally include a description of the problem.
500	This is a server error. Check the logs on the server for the reason for the error. Typically these errors will show up both in the rolling.log and in the event viewer on the web server.
412 PRECONDITION FAILED	On a PUT or DELETE, if the client includes an If-Match header and the ETAG does not match with the current version in the database, this error will be returned. This protects from overwriting another user’s data, but is completely optional and the client system is responsible for including the header if this behavior is desired.
405 METHOD NOT ALLOWED	This is returned if the client has requested to do something we do not support. For example, if a user tries to delete a request using the Lucity Citizen Portal REST API.

Expected return codes and behavior

Return status codes and headers also follow HTTP standards. The following are the possible return codes you will see developing with the REST API.

200 OK	A GET request will return this code if there were no problems with the request. There will be returned in the body of the response. A PUT will also return this status code if it was successful and will return a copy of the object in the body of the response as it currently exists in the database (this might include data changed after calculations, additional defaults, etc.).
201 CREATED	A POST request that creates a new record will return this status code and will return the copy of the object in the body of the response as it currently exists in the database.
204 NO CONTENT	A DELETE request that successfully deletes a record will return this status code. The body of the response will be empty.
304 NOT MODIFIED	A GET response which includes an ETAG may return a 304 not modified if the object in the database has not been modified since the original ETAG was issued.

Lists

All lists will have a trailing backslash (query parameters go after the slash however). For example:

List of work orders and a list of work orders that are in a designated filter

http://restapi.lucity.net/gbaMS/Work/WorkOrders.svc/

http://restapi.lucity.net/gbaMS/Work/WorkOrders.svc/?FilterId=123

List of available code types for MainTaskCode

http://restapi.lucity.net/gbaMS/Work/WorkOrders.svc/MainTaskCode/

ETags

ETags are returned on all GET that return a single record as well as all PUT and POST requests. The system will respect ETags for GETS, PUTS, and DELETES.

For example, if a GET on a single work order is issued and it includes a header with the following:

If-None-Match: "686897696a7c876b7e"

The Lucity REST API will check the version of the work order in the database, if it matches the version provided in this ETAG, the Lucity REST API will return a 304 NOT MODIFIED.

For Updates, ETAGS can be used to make sure that one user does not overwrite another user’s data. If, on a PUT, the following is included on the header:

If-Match: "686897696a7c876b7e"

The Lucity REST API will only make the requested update if the version of the record in the database matches the provided ETAG.

Query Parameters

The following query parameters are supported (not all requests support all query parameters). All of these query parameters are optional.

FILTER	Filter string which should general include a table name. For example: Filter=WKREQ WHERE RQ_STAT_CD < 950 (provided un-encoded here for clarity)
FILTERID	Filter Id that should be used to filter the data. Each module has a list of canned or predefined filters that have been saved by users. This is the AutoNumber that represents that saved filter. These filters are available as a list that you can show users (See Special Functions).
ORDERBY	The property or field name that the data should be sorted by. This is the Autonumber property by default (descending order). For example: OrderBy=StatusCode+DESC
TAKE	Designates how many records should be returned. By default 10 will be returned. The max is limited based on the Lucity Administrator assigned max in Lucity System Settings (max is defaulted to 50).
SKIP	Designates how many records to skip. For example, to get the second set of 15 records, the Skip = 15 and the Take = 15. Skip MUST be divisible by Take. You cannot request Skip = 20 and Take = 15. This will result in a 400 Bad Request error.
FORMAT	format=json or format=xml. The default is xml.
EMAIL	The email address of the requestor. This only is available for the public REST API and is affected by a system setting.
REQUESTNUMBER	The request number. This is only available for the public REST API and is affected by a custom setting
STARTSWITH	Limits returned records to only records that start with the provided text. Only supported on limited endpoints (picklists mostly)
NULLWRITES	Used only on PUT requests. Controls how null values (or missing properties) are handled. By default missing properties or null values (or default values such as 0 for a non-nullable numeric) are ignored in the input. To override this behavior and force these null values to be set, pass NULLWRITES=TRUE. This means that if a property is missing or has a null value, the REST API will attempt to change that value to null on the server (if the property is writable). Do not use this option unless you are certain you will be sending up every property on PUT requests or you may end up overwriting real data.
311ONLY	This parameter is used on problem picklists only and tells the application to only return problems that are marked for 311 in the problem setup module.
PROPERTYID	Used for limit lists for picklists. This property id is the id of the field on a submit form where a user has defined a limit list.
IDLIST	Filters the data to only items where the AutoNumber or unique Id are in the list provided. This is not a text field, it corresponds to the identity column in the dataset. This property in the response objects is always "Autonumber". Used only on GET requests.
SELECTEDIDS	Used for tools to indicate which ids the tool should be applied to.
PROPERTY	Used on POST and PUT $nonpersistent requests only. Used to indicate the last field the user edited and is helpful for the server in figuring out what the object should look like after the user’s edits.
DOCDESCRIPTION	Query parameter used when uploading new documents. Allows for a description to be set on the document. By default the document description is the date and time of the upload.
WARN	Indicates that the code should provide warnings (these will be returned as 409 CONFLICT responses). By default warnings are ignored in the REST API and will not be returned for display to the user.
STARTSWITH	This is a special query parameter only available for certain lookup lists such as category, problem, or standard code type values. For example: STARTSWITH=a will return all code types where the code (and in some cases the type) starts with an a.
COMMONID	Allows for a query based on the common id of an asset. This is only supported in limited inventory and inspection modules. This corresponds to a text value which should be encoded in the request if there is any risk of spaces or special non alphanumeric characters may be used.
INVALIDSTREETTOGENLOC	This setting is used for the Public REST API. If there is a problem with the street name the user provided, that the value should be placed in the non-validated general location field. By default this is false.
STATUSFLAG	Supported for request and work order modules only. Allowed values are CLOSED and OPEN
STATUSDAYS	Works with the STATUSFLAG query parameter. Limits the data returned to only records whose status has changed in the last X days. By default the STATUSFLAG query parameter returns all records (up to the maximum take).
COORDSYS	This is a special query parameter only used with the Citizen Portal REST API. See documentation on configuration for a discussion on this parameter. Available options are COORDSYS=LOCAL, COORDSYS=MERCATOR, COORDSYS=LATLONG