SymetryML JSON API Objects

HTTP Request Body for JSON Objects

You must pass a JSON request body that is appropriate for the service being called. The following table describes the supported request bodies. For a detailed description about these objects, see Appendix A.

JSON Data Structure	Description
DataFrame	Use when learning, forgetting, making predictions and modifying Encoder attributes values. DataFrame contains an attribute name list, an attribute types followed by an array of string. This organization is similar to a comma-separated value (CSV) file, where the first line usually is the header containing the name of each column (similar to the ‘attributes name list’ in our API), followed by n lines that each contain x values (where x usually is the same length as the number of columns in the header). DataFrame contains the following information: * attributeNames = name of the attributes or features in the dataframe. * attributeTypes = type of the attributes. See About Attribute Types. * data = the actual data.
DSInfo	Information about data source.(see DSInfo)
DSListingRequest	Information about listing directory and files from data sources.(see DSListingRequest)
MLContext	Used when building models and conducting data exploration requests. Use to specify attributes, target a request, and specify attribute(s) to use for Exploration requests.(see MLContext)
ExploreContext	List of MLContext that allows passing multiple MLContext when calling the REST exploration service. You can then request the same metric for various attributes or a combination of attributes.(see ExploreContext)

About Attribute Types

In SymetryML, It is possible to specify the type of the attributes in a DataFrame. Attribute type is specified using a single character for each of the attributes in the DataFrame. The following table describes the supported attribute types and their behaviour.

Attribute Type	Description	Details
C	Continuous	Use this to specify numbers.
B	Binary	Only 1 and 0.
S	String	Any String is allowed. Usually used in conjunction with an Encoder in a project (see Encoder Object REST API). If a project does not contain an encoder attribute with this type will be ignored..
L	List	String values separated by |, e.g.** |a|b|c**. Usually used in conjunction with an Encoder in a project (see Encoder Object REST API). If a project does not contain an encoder, an attribute with this type will be ignored.
T	Category	Attribute of these type will see all their different values seen as a different category. Under the hood, SymetryML creates ‘dynamic’ attributes for each the different values. This is a feature in SymetryML since version 3.5 that provides automatic handling of categorical values – usually in the form of string - by creating attributes on the fly in the project to represent them. The attribute being created will have a ‘Binary’ type and its actual name will be of the following form Example: flowertype$versicolor Values will be normalized by: trimming the value and changing it to lowercase.
X	Ignore	Attributes with this type will be ignored.
-	None	Internal Use Only

HTTP Response for JSON Objects

All SymetryML REST requests return a JSON response. Depending on the service requested, the response can contain additional response(s) entity(ies) (see Additional Response Entities below). For a detailed description about these objects, see Appendix A.

About JSON Strict Syntax

As of Version 5.0 SymetryML does not fully conform to the JSON syntax. More specifically, we can return float value like Infinity that are not part of the JSON specification. You might need to change the configuration of your JSON parser in order to allow it to be more lenient.

Main SymetryML Response

Object	Description
JSONResponse	All SymetryML Rest APIs return this object. This object contains the HTTP return code, as well as contextual information if an error occurs. A JSONResponse can also contain additional response entities, depending on the service requested. (see Response Entities)

Additional Response Entities

JSON Entity	Description
DataFrame	DataFrame is returned as a response when using the SymetryML REST service on Data source files. For more information, see DataFrame JSON.
DSInfo	This JSON contains information about a data source. Depending on the type of the data source, the information it contains will be different. Currently, the following data sources are supported: - Amazon S3 - SFTP - HTTP URL - JDBC - Spark RDD - Amazon S3 with Spark processing - Amazon RedShift - Amazon EMR. See DSInfo JSON for more information.
DSListingResponse	This data structure is used to return data source listing information. It allows to list ‘folders’ and ‘files’ from a data source repository. For more information, see DSListingRequest.
JobInfo	Returns the following information about a specific job on the server: - Job type - Job Owner - Whether the job has started yet - Is Job finished - Starting date of a job that has started. - Maximum size of a file to process. - Current size of a file that was processed. It is possible to compute the percentage of completion of a job by computing Current Size / Maximum Size. - In the case of a reducer model, the current size will reflect how much iteration were done so far. For more information, see JobInfo.
KSVDMap	Key String Value Double Map Data structure is an array of map<String, double>. For more information, see KSVDMap.
KSVSMap	Key String Value Double Map Data structure is an array of map<String, double>. For more information, see KSVDMap.
ModelInfo	Contains information about a model. All models have at least the following information: - Attribute Name - Attribute name ID used internally in the model - Attribute Types - Target(s) name - Target(s) name ID from the SymetryML project - modelBuilt = number of models built to eventually create that model. This number is greater than 1 if the model is the result of the Reducer process. - buildTime = overall processing time required to build the model. This value includes reduce time that might have built more than one models. Depending on the type of model, more information can be stored in the form of key/value string pairs.
ProjectInfo	Holds the following information about a SymetryML project: - ID of a SymetryML project - List of attribute names - List of attribute IDs - List of attribute types: - List of model IDs that belong to that SymetryML project - Creation date - Last modification date
ProjectInfoList	List of ProjectInfo.
StringList	Holds an array of string. This response is returned when asking for the list of SymetryML project IDs that was saved on Amazon S3 or when asking for the list of current job ID.
FederationInfo	Hold information about a federation. For more information consult the Federation Learning API.
AwsInfo	Data Structure that contains information about SNS topics, SQS queues and SNS subscriptions for a given AWS user. Please consult the Federated API for more information.
DensityList	The data structure returned by the Density rest call.

REST Call HTTP Return Code

Every service request to the SymetryML REST API returns an HTTP response code and HTTP header information that is appropriate for the service called. The following table lists the HTTP return codes. These return codes can be returned by any REST request.

HTTP Return Code	Description
200	OK, no error
201	CREATED, a resource was created successfully, for instance a project or data source.
202	ACCEPTED, typically returned when an asynchronous REST call return successfully.
400	BAD_REQUEST, the request was improperly formatted or was rejected by SymetryML for containing invalid information.
401	UNAUTHORIZED, the user's credentials were rejected by SymetryML.
409	CONFLICT, typically returned when trying to create an entity like a project or data source that already exists.
500 INTERNAL SERVER ERROR	If an exception was raised while processing a request, this response contains information about the error that was raised.
503 SERVICE NOT AVAILABLE	The SymetryML REST web application is not available. View your server logs to troubleshoot the issue.