Overview (Soda2 API Client 0.9.2-SNAPSHOT API)

API Package (defines the operations)
Package	Description
com.socrata.api	Provides objects that implement all the major Socrata operations (verbs).

Model Packages (defines the "nouns")
Package	Description
com.socrata.exceptions	Defines the errors that can happen when using the Socrata APIs defined in com.socrata.api.
com.socrata.model	Defines the objects that are parameters to APIs, return values to APIs or system objects in the Socrata platform.
com.socrata.model.importer	The model objects (nouns) used by the import operations defined by SodaImporter.
com.socrata.model.requests	The model objects (nouns) used for defining SODA requests.These objects are mainly used internally by the API to provide "retry" logic in the case of 202 retries..
com.socrata.model.search	The model objects (nouns) used for doing searches on the Socrata platform.
com.socrata.model.soql	The model objects (nouns) used for defining SoQL operations.

Utility and Helper Packages
Package	Description
com.socrata.builders	Helper objects to create and manipulate some of the objects defined in com.socrata.model.These are not necassary for using the API, but can be useful.
com.socrata.utils	Helper objects used by the API implementation.

Overview

The Java API provides methods for calling the commonly used APIs provided by the Socrata platform. That being said, by far the most common usages are either updating data or querying data. For querying data, there is only one good way of doing this, which is using the Soda2Consumer api and the SODA Query Language (SoQL) to create queries. For updating data there are two ways to do this, and choosing which one depdends on your scenario.

Updating Datasets

Socrata offers two workflows for updating data:

The Upsert Flow is a much simple process where you simply call an upsert operation that allows you to add/remove/update data in a dataset in a bulk operation. This is a more light weight way to update datasets and should be considered the default updating mechanism. If updating datasets more than once an hour, you should definitely use this flow.
The Publishing Flow is a process where you first create a working copy of the dataset. This working copy is only seen by your client until you do your appropriate updates and then publish it. This method provides some safety in terms of allowing you to do many updates through several API calls and not let your users see them mid way, however, it is expensive. You should only really use this if you are updating datasets less than once every two hours and you are updating a lot of the dataset.

The Upsert Flow

The upsert flow is the easiest way to update data and is often the recommended version. This simply allows you to send up updates in a CSV file or a JSON object. An example of the simplest way to call this is:


    Soda2Producer producer = Soda2Producer.newProducer(url, userName, password, token);
    UpsertResult results = producer.upsertStream(UPDATE_DATA_SET, HttpLowLevel.CSV_TYPE, csvStream);
    if (results.errorCount()) {
        //If there are data errors, throw so the data can be checked by a human to make sure it is correct
        throw SomeError;
    }

The Publishing Flow

The publishing flow is a bit more involved. It entails copying a dataset, doing work on it, and then publishing it. As mentioned above, the copy and publishing steps are potentially expensive, so this flow should only be done when you need it. It is likely in the future, Socrata may restrict the number of working copies allowed on a dataset per hour to prevent abuse.


    SodaImporter importer = SodaImporter.newImporter(url, userName, password, token);

    DatasetInfo  unpublishedView  = importer.createWorkingCopy(UPDATE_DATA_SET);
    DatasetInfo  appendResults    = importer.replace(unpublishedView.getId(), CSV_TO_REPLACE_WITH, 1, null)
    DatasetInfo  publishedResults = importer.publish(appendResults.getId());