Plum Fuse

API: Uploading CSV Data to a Table

This API request is initiated with an POST to the following URL:

http://quickfuseapps.com/api/1/sdb/upload/csv

A CSV file is required for this request. The format of the CSV file should be:

column_1,column_2,column_3
123,456,789
other,data,values

The first row of the CSV is reserved as a header row describing the fieldnames for the data in proceeding rows. For more specifics on the CSV format, see the section below.

Since a file upload is expected, the request must be POST'ed with Content-type: multipart/form-data.

Example usage

In these examples, customerdata.csv is a CSV file with 3 rows of data.

Upload and merge example: Inserts data from the file customerdata.csv into the table called customers owned by the user. Existing data is left untouched.

$ curl -u username:password -F tablekey=username:customers -F mode=merge 
  -F csv=@customerdata.csv http://quickfuseapps.com/api/1/sdb/upload/csv

This example returns the following response if successful:

{
  "rows": 3,
  "replace": false,
  "tablekey": "username:customers",
  "result": true
}

Upload and replace example: Same as previous, any data already in the table customers is deleted and replaced with the uploaded data.

$ curl -u username:password -F tablekey=username:customers -F mode=replace 
  -F csv=@customerdata.csv http://quickfuseapps.com/api/1/sdb/upload/csv

This example returns the following response if successful:

{
  "rows": 3,
  "replace": true,
  "tablekey": "username:customers",
  "result": true
}

Parameters

Required

  • tablekey (string) - Identifies the table of the Simple Database that will receive the uploaded data. This is in the format <tableowner>:<tablename>. It is case and whitespace sensitive. <tableowner> is the full username of the owner of the table. Valid table names contain only letters, numbers, and the underscore _ character.
  • mode (one of merge or replace) - merge mode appends the CSV data to the end of the table, leaving existing data untouched. replace deletes all data in the table, replacing it with the CSV data. Use caution with the replace mode. Data that is replaced cannot be recovered.
  • csv (file in CSV format) - The data to be inserted or replaced. Details of the format of this file are in the next section.

CSV Format Specification

There is little consensus over what constitutes a valid CSV since the format was used informally long before it was formally specified in 2005; therefore, the following is a description of the CSV format that our webservices understand. As much as possible, we've followed the Basic Rules that most CSV parsers implement, which is also the format that Microsoft Excel exports and imports most easily.

  1. Each record is one line terminated by a line feed (ASCII/LF=0x0A) or a carriage return and line feed pair (ASCII/CRLF=0x0D 0x0A), however, line breaks can also be embedded in values as described in rule 5.
  2. Fields are separated by commas or tabs. If we discover a tab character in the first line of your CSV, we will use the tab character as a delimiter instead of the comma.
  3. Fields with embedded delimiter characters (whether comma or tab) must be enclosed within double-quote characters.
  4. Fields with embedded double-quote characters must be enclosed within double-quote characters, and each of the embedded double-quote characters must be represented by a pair of double-quote characters.
  5. Fields with embedded line breaks must be enclosed within double-quote characters.
  6. Fields with leading or trailing spaces should be enclosed within double-quote characters, although leading and trailing spaces for unquoted values are not trimmed.
  7. Fields may always be enclosed within double-quote characters, whether necessary or not.

A limitation of the Simple Database is that fields may not contain more than 1024 bytes each, and tables should not have more than 200 columns.

Response

The following is an example response when the upload has successfully completed.

{
  "rows": 100,
  "replace": false,
  "tablekey": "owner:tablename",
  "result": true
}
  • rows is a count of the total rows of data that were parsed from the CSV and inserted.
  • replace is true if the operation mode was set to replace, and false otherwise.
  • tablekey is the tablekey for the table that was affected.
  • result is always true if the request was successful.

If there was an error, an error response is issued.

api/sdb_upload_csv.txt · Last modified: 2010/06/13 23:11 (external edit)