Imports API

Endpoint for uploading and importing file data into GeoServer. All imports are asyncronous; the typical workflow to import a data store is:

1. POST to upload a File or connect to a database
2. Poll GET until ready for import
3. PUT to select what tasks/layers to import
4. Poll GET until import has completed
5. (Optional) PUT to update failed tasks. Go to 4.

# View an Import

Get information about an existing import

GET /api/imports/<workspace>/<id>

Response:

With the exception of an uncaught server error the response is always 200 with a payload that looks something like the folllowing:

{
    "id": 0,
    "task": "Processing data usa-merc.tif"
    "importerEndpoint":"http:\/\/localhost:8000\/geoserver\/geoserver\/rest\/imports\/1",
    "preimport": [],
    "running": [],
    "imported": [
      {
        "task": 0, 
        "name": "stipple.shp",
        "type": "file"
        "layer": {
          "name": "stipple", 
          "workspace": "opengeo",
          ... rest of layer definition
        }
      }
    ], 
    "pending": [
      {
        "task": 1, 
        "name": "usa-merc.tif",
        "type": "file"
        "problem": "NO_CRS"
      }
    ],
    "ignored": [], 
    "failed": []
    "status":"complete"
    "tasksComplete":2
    "tasksTotal":2
}

The response is an object with 12 properties. If this is a new import, and the context has not yet been created, only id and task will be included.

• id - The identifier of this import job, needed to make modifications to it
• task - A textual representation of the current task. Not included if no task is currently running.
• importerEndpoint - REST endpoint to manage this import using the GeoServer Importer REST API
• status - The current status of the import. May be "pending", "running", or "complete"
• tasksComplete - The number of tasks that have been processed and have either been successfully imported or given an error.
• tasksTotal - The total number of tasks associated with this import
• preimport - Tasks that have been identified but not yet imported. Used by the database import and asynchronous import
• running - Tasks that are currently running. Only used by asynchronous import
• completed - Tasks that were successfully imported. Each task contains the resulting layer representation.
• pending - Tasks that require further input from the user before being imported. The most common case being missing projection information. Each task contains a property named "problem" that identifies the issue.
• ignored - Tasks that correspond to files that GeoServer doesn't recognize. Usually these are README files or other metadata files that don't correspond to data to be imported, but are present in the uploaded archive.
• failed - Task that failed for some other reason. Each task contains an error trace that provides more information about the failure.

# Import a File

Upload a file and prepare for import.

POST /api/imports/<workspace>

Request:

Multipart form upload of zip file or other spatial file.

Response:

With the exception of an uncaught server error the response is always 200 with a payload that looks something like the folllowing:

{
    "id": 0,
    "task": "Processing data usa-merc.tif"
}

# Import a Database

Connect to a database and prepare for import.

POST /api/imports/<workspace>

Request:

JSON Connection parameters to the database. Refer to the Formats API.

Response:

With the exception of an uncaught server error the response is always 200 with a payload that looks something like the folllowing:

{
    "id": 0,
    "task": "Processing data usa-merc.tif"
}

If you try to import a database that already exists in the workspace, the import will not run, and the API will instead return a payload describing the existing store, similar to the list response in the Stores API.

# Update an Import

Execute an import started with POST, or update a pending task and reimport.

PUT /api/imports/<workspace>/<id>

Request:

The request payload can be a list of task objects with any additional data that needs to be specified by the user. This example (re)imports of task 0, and sets the projection and re-imports task 1:

{ 
    "tasks":[
        {
             "task": 0
        },
        {
             "task": 1,
             "proj": "epsg:3857"
        }]
}

Alternatively, the request can specify a filter to select tasks to import. Currently "ALL" is the only supported filter. This would import all tasks:

{ "filter":"ALL" }

Response:

The response payload is the updated task object reflecting the new state of the task. If the task successfully executed the result will be the "completed" representation as above. If a task is already running (indicated by the top-level task element of the GET response, the update will fail and return an error. This is to prevent two tasks from running and updating the same data at the same time.