Salesforce Bulk API 2.0 Swagger Documentation

Salesforce's Bulk API 2.0 in one easy-to-swallow, YAML-flavored, Swagger file.

tl;dr

Want to skip the chitchat and just grab the Swagger?

Overview

Let's face it: Salesforce's documentation is not always the greatest—especially their API docs. Fortunately, there is a super common, easy-to-read standard for documenting APIs called the Open API Specification (OAS), often referred to as "Swagger".

👀

OAS vs Swagger
Swagger initially referred to both an API documentation standard and a set of tools for creating and maintaining API documentation. However, in 2015, the OpenAPI Initiative (OAI), under the Linux Foundation, took over the specification, renaming it the OpenAPI Specification (OAS) and expanding it into a widely adopted standard for defining APIs.

Currently, Swagger refers only to the toolset, which includes Swagger Editor, Swagger UI, and SwaggerHub, all of which support the OpenAPI Specification. This toolset allows users to create, test, visualize, and document APIs in a standardized format, but it is just one among several tools available for working with OpenAPI-defined APIs.

Even though there is a technical difference, the terms "Swagger" and "Open API" are often used interchangeably by the developer community.

Why the Bulk API?

The Bulk API is an often-used, sometimes abused, API that allows for bulk CRUD operations. The 2.0 version is particularly good for bulk queries as it does not count against the rolling 24-hour limit.

In Bulk API 2.0, only ingest jobs consume batches. Query jobs don’t. For details, see How Requests Are Processed in the Bulk API 2.0 Developer Guide.
Salesforce Docs - Bulk API and Bulk API 2.0 Limits and Allocations

Off all of the APIs offered by Salesforce, the Bulk API is one of the most common when integrating Salesforce with other internal business applications. It's also easy to "Swagger-fy" since it is not schema-dependent. A consumer will need to understand your org's particular schema to construct a CSV payload, but the field API names are not hard-coded into the Swagger schema.

Why Swagger?

It's Easy for Developers to Read and Reason About an API

Many times I've had to explain the ins and outs of this funky little API to non-Salesforce developers. This often starts with me sending a link to Salesforce's docs which tend to be, well, Salesforce-y. If you've been around Salesforce for a while, you know what I'm talking about. However, developers from other tech stacks often get used to seeing "Swagger style" documentation for APIs.

You may have seen a page that looks like this...

...This is Swagger Documentation.

Not only do we get some pretty colors and icons, but we can also drill down into each endpoint and see the request and response schemas, the required headers and parameters, and even success and error examples.

Animation showing Swagger Documentation Details

It's Easy for Machines to Read

Now, this gets to the heart of the problem I was trying to solve with this. Having good-looking docs is certainly a great thing, but the true superpower of Swagger is that it is written in a structured format and must adhere to a specification. This means that many systems and applications can ingest a Swagger file, saving you from the time-consuming, error-prone task of entering all of the details about an API by hand.

A great example would be using an API Gateway like Apigee or Mulesoft to virtualize an API by simply uploading a Swagger file. This was my use case, but it can do a lot more, such as:

Automatically generate code designed to interact with your API in many languages
Create manual and automated tests for your API
Allow other systems that consume your API to quickly onboard.

Get the Swagger

Option 1: View Directly in the Swagger Editor

Option 2: Get it from Github

Was this Helpful?

If this solved a problem for you, or made your work easier and want to say thanks, feel free to tip your content creator. You can also pay me in Github stars 🤩!!