• What you will find here
• Response status codes
• Authentication
  • By query params
  • By header
• Examples
  • Creating and publishing a new application
    • Creating an application
    • Creating a version
    • Uploading a version
      • Uploading chunks
    • Processing the upload
    • Job monitoring
    • Looking for errors
    • Publishing it
• API Specification (OpenAPI)

What you will find here

This is a documentation page about PatchKit API (Version 1). This API allows any user with the API Access (must be enabled on your plan) to manage applications on their PatchKit account.

The examples here are pretty basic but should help you to understand how to work with these entities. If you need any help, please don’t hesitate contacting the support.

If you’re looking for the full API specification, you can find it here.

Response status codes

PatchKit API uses HTTP status codes to indicate the operation result. Here’s the list of the most common return codes.

Authentication

You can authenticate with PatchKit API with the API Key. You can find your API Key on your Account page. Do not share your API Key with anyone you don’t trust. It gives full access to your account. You can always invalidate your API Key by generating a new one on the same page.

Note that not every endpoint requires authentication. Some endpoints are public (e.g., application info). Passing API Key to these endpoints won’t harm, though.

You can authenticate the request in one of two ways:

By query params

Simply put api_key parameter within your query:

https://api2.patchkit.net/resource?api_key=52293bd82f5cbd049cf398c3f52547aa

By header

A more elegant way may be to use an X-Api-Key header:

GET /resource HTTP/1.1
X-Api-Key: 52293bd82f5cbd049cf398c3f52547aa

Examples

Creating and publishing a new application

If you’re integrating the PatchKit upload system on your web page, this is the first thing you might be trying to integrate.

Creating an application

curl -d "name=my_new_app&platform=windows_x86_64" -H "X-Api-Key: APIKEY" -X POST https://api2.patchkit.net/1/apps

This creates a new application entity with a given internal name.

{
  "id": 1,
  "secret": "secret_string",
  "platform": "windows_x86_64",
  "name": "my_new_app",
  ...
}

For this entity, use the application secret to identify it.

Creating a version

Before you can upload a new application content, you need to create a new version. As you do have your application created, it’s pretty straightforward:

curl -d "label=1.0" -H "X-Api-Key: APIKEY" -X POST https://api2.patchkit.net/1/apps/APP_SECRET/versions

On success, it will return a JSON in the body:

{
  "id": 1,
  "label": "1.0",
  "publish_date": 0,
  "draft": true,
  ...
}

Uploading a version

Now, as we have our version created, we need to create a new Upload object. Upload objects allow to upload large payload in chunks and even resume the upload or network failure or if the upload has been intentionally paused.

Note that you need to upload the application as one file. It has to be a ZIP file using STORE or DEFLATE algorithms. Note that DEFLATE64 is not supported. You also need to know the zip file size before the upload starts.

curl -d "total_size_bytes=1234567" -H "X-Api-Key: APIKEY" -X POST https://api2.patchkit.net/1/uploads

As a response, you will receive a JSON with created upload id:

{
  "id": 1
}

Uploading chunks

We recommend splitting the uploaded content into 10-megabyte chunks. Having that, you can try uploading your chunks:

curl -F "chunk=@/tmp/chunk.data" -F "md5=ff15aae3a7a1f9701ec4c7ade37d7bf9" -H "X-Api-Key: APIKEY" -H "Content-Range: bytes 0-10485759" -X POST https://api.patchkit.net/1/uploads/UPLOAD_ID/chunk

Passing md5 parameter is optional. If you do, the uploaded chunk MD5 sum will be validated against the value of the md5 parameter and will return HTTP 412 if the validation fails. You should try to re-upload that chunk if it happens.

On successful upload of the chunk, you should receive a 201 status code.

Processing the upload

As soon as all the chunks are uploaded, the application files need to be converted to a format required for the distribution process. This includes creating an encrypted content file and delta (diff) file. The processing time is dependent on the application size and can be repeatably queried through the API.

curl -F "upload_id=UPLOAD_ID" -H "X-Api-Key: APIKEY" -X PUT "https://api2.patchkit.net/1/apps/APP_SECRET/versions/VERSION_ID/content_file"

This returns a JSON with job_guid field:

{
  "job_guid": "5776de94-56dc-4e8a-8992-1c1d9da1410c"
}

Job monitoring

While you have the job_guid (UUID), you can now query the progress. You do that by sending a GET request:

curl "https://api2.patchkit.net/1/background_jobs/JOB_GUID"

In response, you should receive something like this:

{
  "time_started": "2021-10-19T11:14:50.176Z",
  "time_finished": null,
  "progress": 0.1,
  "pending": true,
  "finished": false,
  "status": 0,
  "status_message": "waiting for free worker..."
}

The most important field is the progress field that should be represented as a % progress to the user. Then, status message can be displayed as an additional information to what is going on. The job is considered finished only when the finished field returns true.

Looking for errors

When the application has been processed, we need to check if there are any processing messages or processing errors. Any error is critical, so no application can be published that has at least one of those.

To get version processing information, fetch the version info:

https://api2.patchkit.net/1/apps/APP_SECRET/versions/VERSION_ID

In response, you will receive a pretty big JSON again, but focus on those two fields:

{
  ...,
  "has_processing_error": true,
  "processing_messages": [
    {
      "severity": "info",
      "message": "string"
    }
  ]
}

The has_processing_error field is the most critical. If set to true, it means that PatchKit couldn’t finish the processing stage by a critical error. You won’t get the error message, but it’s safe to assume that something went wrong with the upload process. Usually, re-uploading it again should help.

If there are any elements in processing_messages, you should check if there are any errors ("severity": "error"). Errors will block the version from being published; therefore, this is a piece of valid information to the user of what should be fixed. Warnings ("severity": "warning") and infos ("severity": "info") may be ignored, but it’s highly recommended to at least present warnings to the user.

Publishing it

If there are no errors, you can now publish the application version:

curl -H "X-Api-Key: APIKEY" -X POST https://api2.patchkit.net/1/apps/APP_SECRET/versions/VERSION_ID/publish

This time to get the publishing process, you need to query the version itself. Publishing is not a job (currently) because even if all files have been published, the entity itself can still be in an unpublished state (scheduled publishing).

https://api2.patchkit.net/1/apps/APP_SECRET/versions/VERSION_ID

Look for these fields:

  "pending_publish": true,
  "published": false,
  "publish_progress": 0,
  "publish_time": 0

• pending_publish field tells if the version is currently in the publishing stage.
• published set to true indicates that the version is now publicly available
• publish_process can be used to display % progress to the user
• publish_time if set anything but 0 and published is false at the same time, it means that the publish date & time has been scheduled to the future. The progress can be at 1 most of the time here, but the published will stay false until the publish_time is reached.

API Specification (OpenAPI)

You can read the full specification here.