Importing content into a TypePad Blog

TypePad offers a specialized import API to make it easier to import posts, pages and comments in bulk into a TypePad blog. This page describes the import process and links to the reference documentation for the endpoints involved in the process.

The primary advantage of this specialized mechanism is that it supports bulk-loading of data to reduce per-item overhead on imports. However, this mechanism also bypasses the normal event delivery and email notification systems so that an import will not cause notification spam. This does however mean that content posted via this mechanism will not appear on TypePad Profiles or on any user's activity reader.

Import Workflow

The high-level steps for import are the following:

  • Obtain OAuth credentials for the user who owns the blog that will be the target of the import.
  • Use those credentials to open an import job for the target blog.
  • Submit batches of post, page and comment assets into the import job.
  • Close the import job to finalize the import.

These steps are described in more detail in the following sections.

Obtaining OAuth Credentials

The credentials used for import are standard TypePad API user credentials as described in the authentication guide. An importer application must follow the steps on that page to obtain an OAuth token for the user that owns the blog that the content will be imported into.

It is not possible to import into a user's blog with user credentials that were granted with the access=app_full argument.

Opening an Import Job

An import job is a container for some state about an import, including some import statistics that may be useful for reporting or resuming a partial import To open an import job, you use the /blogs/<id>/begin-import action endpoint with the id of the blog you wish to import into. You can obtain a list of blogs for your authenticated user by requesting the /users/<id>/blogs endpoint with the special user id @self, at /users/@self/blogs.json. This works only when authenticated using user credentials.

The following is an example request to open an import job:

POST /blogs/6a012877b13de7970c012877b13df1970c/begin-import.json HTTP/1.1
Content-Type: application/json
Host: api.typepad.com
 
{}

If successful, the response status will be 200 OK and the payload will have a job property whose value is an ImporterJob object representing the job that was created:

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "job": {
        "urlId": "ij15425643ab35312364572344abef3456",
        "matchUsers": false,
        "createUsers": false
    }
}

The urlId property here is used as the id for the other endpoints used during the import process.

The response status will be 403 Forbidden if the blog is not owned by the user whose credentials were used or if the credentials used do not grant access to the user's TypePad content.

Submitting Posts, Pages and Comments

Request

The actual content for the blog is submitted via one or more calls to the action endpoint /import-jobs/<id>/submit-items.

This endpoint expects a request body containing a JSON object with a single property called items, whose value is an array of ImportPost, ImportPage and ImportComment objects. These object types are similar to their relatives Post, Page and Comment used elsewhere in the API but have slightly different properties to accomodate the requirements of the import process. The documentation pages for those object types describe what properties they support.

The foreignId property of all of the asset types is required. This is any string of significance to the client as long as it's unique across all assets submitted for a given import job. These identifiers will be used to report success and failure in responses and also to connect comments with their associated posts.

The objectType property is also required and must be set to either ImportPost, ImportPage or ImportComment to tell the system what kind of asset the object represents.

Response

The response from this request contains a JSON object with two properties, succeeded and failed. Both of these is an object whose properties correspond to foreignId values of submitted assets.

The succeeded object's values are the TypePad-assigned asset ids that correspond to each of the assets that was successfully imported, and these ids can be used to retrieve the assets using the /assets/<id> endpoint if desired.

The failed object's values are themselves objects which contain a single property message. The message is a developer-oriented error message describing why each asset could not be imported. These messages are intended to be useful during import client development and are not suitable for showing to end-users of import tools.

Here is an example response payload showing both successes and failures:

{
    "succeeded": {
        "23453": "6a0137f4ea9519033d0137f4eb8127033d",
        "5644": "6a0137f4ea9519033d0137f4eb811b033d"
    },
    "failed": {
        "2345": {
            "message": "Anonymous comments are not permitted for this asset"
        }
    }
}

In this example, the asset whose foreignId property was 2345 could not be imported because it was an anonymous comment posted in response to a post where anonymous comments are not allowed. However, the assets that the client calls 23453 and 5644 were successfully imported and have the TypePad asset ids shown.

Splitting Large Datasets

It is suggested that you send items in batches of 50 to 100 items per payload. You can make as many requests to this endpoint as necessary to complete your import, but note that clients of this import API are subject to the rate limiting rules and therefore may have to pause during a large import to avoid being blocked.

Data Ordering

The order in which you submit data into an import job does not matter except for the rule that a comment must be posted after the post or comment that it is directly in reply to. If you submit a comment whose parent asset is not yet known to TypePad that comment's import will fail.

Submitting Media Assets

The item submission endpoint described above does not support submission of photos and other files. These are generally larger payloads and so the benefit of bundling several together in one request is not as pronounced as for text-based assets.

Therefore rather than providing a specialized media upload endpoint the import system simply provides the endpoint /import-jobs/<id>/media-assets which is just a convenience wrapper around the standard /blogs/<id>/media-assets endpoint used to upload media files for use in a blog. While authenticating with appropriate credentials a client may send a POST request to this endpoint with an appropriate Content-Type and a payload of that type in order to create an asset from that payload. For example, a JPEG image can be submitted using a Content-Type value of image/jpeg and will result in the creation of a Photo asset.

Note that it is the client's responsibility to rewrite any image URLs in uploaded content to point to the corresponding image URL on TypePad. The imageLink property on the Photo asset created for an uploaded photo is an ImageLink object that has the information necessary to embed the image at a variety of sizes.

Obtaining Job Statistics

A few statistics are maintained for each job during its lifetime, which clients may wish to use to report progress to users or to identify where to resume from in the case of an interrupted import.

The statistics are available as part of the ImporterJob object returned from the endpoint /import-jobs/<id>. The lastForeignId, lastSubmitTime and assetsImported properties become available after the first access is successfully imported and are updated throughout the import job.

Closing the Import Job

Once all assets have been imported, a client should close the import job to free the resources associated with it and close the temporary channel by which assets can be inserted. This is done via a call to the /import-jobs/<id>/close-job action endpoint.

Automatic Job Cleanup

If you leave a job open after use, it will be cleaned up approximately four hours after the last request to the /import-jobs/<id>/submit-items endpoint. If for some reason a client needs to hold open a job for a while without submitting any items, it is acceptable to submit an empty list to keep the job alive.

The lastSubmitTime property of an ImporterJob object gives the time from which the four hour cleanup time is measured.

References

The endpoints used during the import workflow are:

The object types used during import are: