The packaging API allows users to package data of interest in many different formats. There is currently no way to package data through a graphical interface so users will need to be comfortable using the REST API directly. Rich Data Services tries to make it as easy as possible for users to use the packaging API, or to build their own interfaces that use it. 

View all Available Formats

To begin, users will need to know the available packaging formats that RDS supports. To view all the available packaging formats:

http://host/rds/api/package/types

[
    "CSV",
    "DELIM",
    "FIXED",
    "DDI_C122",
    "DDI_C21",
    "DDI_CNES",
    "DDI_C25",
    "DDI_L31CO",
    "DDI_L31RP",
    "DDI_L31SU",
    "DDI_L32RP",
    "DDI_L32SU",
    "SSS11",
    "SSS20",
    "SAS",
    "SPSS",
    "STATA",
    "R",
    "MATHEMATICA",
    "STAT_TRANSFER",
    "MYSQL",
    "ORACLE",
    "MS_SQL",
    "HYPER_SQL",
    "POSTGRES_SQL",
    "MONET_DB",
    "GOOGLE_BQ",
    "GOOGLE_FUSION",
    "SDA",
    "VERTICA"
] 

View Format by Category

The formats that RDS supports can be broken down into three categories, data (flat files), metadata (standards compliant XML), and scripts (syntax to recreate the data in databases or statistical packages). To view the formats that are in each category use the category parameter. These lists of formats are designed to allow users to easily distinguish between different formats. Once a format is chosen users can retrieve the options to configure the output.

http://host/rds/api/package/types?category=data

[
    "CSV",
    "DELIM",
    "FIXED"
]

http://host/rds/api/package/types?category=metadata

[
    "DDI_C122",
    "DDI_C21",
    "DDI_CNES",
    "DDI_C25",
    "DDI_L31CO",
    "DDI_L31RP",
    "DDI_L31SU",
    "DDI_L32RP",
    "DDI_L32SU",
    "SSS11",
    "SSS20"
]

http://host/rds/api/package/types?category=scripts

[
    "SAS",
    "SPSS",
    "STATA",
    "R",
    "MATHEMATICA",
    "STAT_TRANSFER",
    "MYSQL",
    "ORACLE",
    "MS_SQL",
    "HYPER_SQL",
    "POSTGRES_SQL",
    "MONET_DB",
    "GOOGLE_BQ",
    "GOOGLE_FUSION",
    "SDA",
    "VERTICA"
]

Format Options

Once a format is selected the options available for that format can be retrieved by specifying the format type as follows.

http://host/rds/api/package/types/{type}

http://host/rds/api/package/types/FIXED

{
    "objectId": "47f2a70a-158c-4524-bd85-eee8880a5067",
    "type": "FIXED",
    "optionProperties": [
        {
            "description": "File name", // A human readable description of what this option is about
            "enumValues": [],           // If this option was of type "ENUM" the enumerated values could be found here
            "label": "File name",       // A label for the option, typically what will be shown to the user
            "name": "fileName",			// The property name, this must not change
            "type": "TEXT",				// designed to help those building a UI be able to decide the best input to use. 
										// Possible types are: BOOLEAN, DATE, ENUM, FILE, NUMBER, PASSWORD, TEXT, TEXTAREA
            "value": "",				// The value specified by the user, if there is a default value to begin with this will be filled out
            "repeatable": false,		// specifies if this option can be repeated
            "required": true,			// specifies if this option must be filled out
            "readOnly": false			// specifies if the value can be changed or not
        }
    ]
}

Building a Package Request

A packaging request will provide Rich Data Services with an array of format options that can be used to produce the desired files. To create the packaging request the user must:

1. Get the package request object.

   http://host/rds/api/package

   {
       "orderId": "cce1dcb8-77d3-4676-ac2d-452d89c20424",  // The packages unique order ID which can be used to check the status once the packaging request is submitted
       "options": []                                       // The array of format options, currently empty. 
   }

2. Get and fill out any format options, see the example in the section above. 

3. Add the filled out format options to the package request.

   {
       "orderId": "cce1dcb8-77d3-4676-ac2d-452d89c20424",
       "options": [
           {
               "objectId": "26ac8903-c319-4e3d-874a-08f91673e1bb",
               "type": "FIXED",
               "optionProperties": [
                   {
                       "description": "File name",
                       "enumValues": [],
                       "label": "File name",
                       "name": "fileName",
                       "type": "TEXT",
                       "value": "myfile.txt",  // the value has been populated by the user
                       "repeatable": false,
                       "required": true,
                       "readOnly": false
                   }
               ]
           },
           ...  // add any additional format options that you want.
       ]
   }

4. Once the package request has been filled out with the desired options it can be passed back to the server through a POST at:

   http://host/rds/api/catalog/{collectionId}/{viewId}/package

   This will send the order off to the server and start the packaging process. The packaging process will be queued and run in the background, so it may not be immediately available. After posting the packaging request, the following information should be returned:

   {
       "orderId": "cbe2dab8-77d3-5636-ac2d-952d95c20424",
       "message": "SUCCESSFULY QUEUED"
   }

5. The orderId that is returned can be used to check the status of the packaging process by getting:

   http://host/rds/api/order/{orderId}/status

   This will return information about the status of the packaging process, along with an number indicating the percent completed. 

   {
       "id": "77fbdc4d-3935-4339-a5da-81605cf8208f", // back end packaging ID not to be confused with the orderId
       "status": "COMPLETED",
       "completed": 100,
       "completionDetails": {
           "details": "Package with orderId cbe2dab8-77d3-5636-ac2d-952d95c20424 is ready for download."
       }
   }

6. When the process indicates that the package is completed and ready for download the orderId can can be used to download a compressed file containing the requested files:

   http://host/rds/api/order/{orderId}/download