Skip to content

Raw REST API ⚠

Atlan University

Walk through step-by-step in our intro to custom integration course (30 mins).

Not for the faint of heart

There are a number of details and nuances to understand about the underlying REST APIs to use them most effectively:

  • the underlying REST API communications (HTTP protocols, methods, headers, endpoint URLs, response codes, etc)
  • translating the complex JSON structures for each request and response payload
  • knowing exactly which values are required (and which aren't) depending on the object you're interacting with, what operation you're carrying out, etc
  • (including which exact string (and capitalization) to use for values that are really enumerations behind-the-scenes)

Ultimately, all pull-based integration mechanisms (including the SDKs) use the REST API; however, the SDKs also encode best practices to avoid the need to understand all these details and low-level nuances.

If you want to adopt these best practices from the start, we would strongly recommend directly using any of our SDKs rather than the raw REST APIs directly:

That being said, we have documented the raw REST API interactions in most cases. So if you really want to interact with the APIs directly, there should still be some guidance — anywhere you see Raw REST API gives details on endpoint URLs, methods, and payloads.

Postman

If all you really want to do is some initial experimentation directly against the API, you can use Postman .

Check out our Getting started with the APIs article for a walkthrough of setting this up.

OpenAPI spec

Why not just publish an OpenAPI spec?

We did try this in the past, as we liked the idea of generating client libraries using tools like the OpenAPI Generator .

Unfortunately, in our own testing of these tools, we found that:

  • We could generate code that is free from syntax errors, but
  • the generated code was not fully functional.

Problems we found:

  • The generated code drops significant portions of data from payloads. (Our APIs are payload-rich and endpoint-light, while the generators seem to favor endpoint-rich and payload-light APIs.)
  • The various objects the generator creates often make developer consumption cumbersome — long, difficult-to-read object names; many variations of similar objects; and so on.
  • The generated code naturally does not include any validation that can't be encoded in the OpenAPI spec. To add this we'd need to wrap the generated code with another layer anyway.

After several attempts at mangling the OpenAPI spec to meet the constraints of the code generator, we eventually decided to go the way we've seen other API-first companies adopt. We found very few API-first companies appear to rely on these code generators, but rather directly maintain their own SDKs for which they may have their own code generators. (Which is in fact exactly what we're doing as well.)

Request for feedback 🙏

If you use the raw REST APIs rather than one of the provided SDKs, we would love to understand more. If you can spare a few minutes to fill out our survey , we would be very grateful!