Palantir Conjure

Conjure is an opinionated toolchain used to define APIs once in a concise, human-readable YAML format and then generate type-safe client and server interfaces in multiple programming languages. It is designed to eliminate serialization bugs and abstract away low-level networking details through ergonomic, idiomatic interfaces.

Key benefits include:

• Cross-language compatibility: Enables teams to work together across different language stacks.
• Type safety: Generates clean abstractions that reduce errors in network requests.
• Backwards compatibility: Helps preserve compatibility so old clients can communicate with new servers.
• Domain modeling: Supports expressive types like enums, union types, maps, lists, and sets.

The extensions section is a map of named extensions used to convey metadata about definitions without modifying their core semantics.

Important Implementation Rules:

• The structure of an extension is user-defined.
• Consumers of an extension should treat its presence as optional.
• Consumers must be tolerant of unknown fields within an extension.
• Extensions must not change the semantics of the definitions they describe.

{
  "extensions": {
    "productVersion": "1.0.0"
  }
}

How container types are represented in JSON:

• optional<T>: Serialized as JSON(T). If the value is absent, the key should be omitted from JSON Objects, or set to null. Inside a JSON Array, an absent optional must be serialized as null.
• list<T>: Serialized as a JSON Array. Order must be maintained.
• set<T>: Serialized as a JSON Array. Order is insignificant.
• map<K, V>: Serialized as a JSON Object. Keys are strings. For optional<?> values, the key should be omitted if the value is absent, though null is permitted.

To ensure robust communication, Conjure follows these compatibility rules:

• Forward compatible clients: Clients must tolerate extra headers, unknown fields in JSON objects, and unknown variants of enums and unions.
• Server field strictness: Servers must reject unexpected JSON fields to help developers catch bugs early.
• Server header tolerance: Servers must tolerate extra headers not defined in the endpoint (e.g., X-Forwarded-For).
• Enum/Union round-tripping: Clients should be able to round-trip unknown variants of enums and unions.
• CORS: Servers must support the HTTP OPTIONS method for browser preflight requests.
• Void endpoints: Clients must tolerate an endpoint expected to return no value actually returning an arbitrary JSON value.

Build tools (such as gradle-conjure) are designed to integrate Conjure CLIs into specific build ecosystems. They are intentionally named differently from code generators to avoid confusion. They do not use the conjure-<foo> pattern.

For the Palantir-supported gradle-conjure tool:

• Maven coordinates: com.palantir.gradle.conjure:gradle-conjure:<version>
• Gradle plugin name: com.palantir.conjure
• Git repository: gradle-conjure

Conjure allows you to define several kinds of named types that can be referenced throughout your definitions:

• Object: A collection of named fields, where each field has its own Conjure type.
• Enum: A type consisting of named string variants (e.g., RED, GREEN, BLUE).
• Alias: A named shorthand for an existing Conjure type, used to improve readability.
• Union: Also known as 'algebraic data types' or 'tagged unions', these represent different named variants, each of which can contain different types.

Compliance for a Conjure-generated client is categorized into three requirements based on the wire specification:

1. Understand spec-compliant server responses: The client must correctly deserialize valid responses.
2. Always send spec-compliant requests: The client must generate requests that follow the wire spec.
3. Reject non-compliant server responses: The client must fail when receiving responses that violate the spec.

Note: Client-side and server-side serialization requirements differ. For example, clients must tolerate extra fields in a server response to allow for forward compatibility, whereas servers may reject unknown fields in a JSON request body.

Query parameters use the Conjure paramId as the query key.

• Optional values: If a parameter of type optional<T> is not present, the key must be omitted from the query string.
• Lists and Sets: For list<T> or set<T>, each value results in one key=value pair separated by &. For list<T>, the order of values must be preserved.
• Serialization: Values must be serialized using the PLAIN format and any reserved characters must be URL encoded.

demoEndpoint:
  http: GET /recipes
  args:
    filter:
      param-type: query
      type: optional<string>
    limit:
      param-type: query
      type: optional<integer>
    categories:
      param-id: category
      param-type: query
      type: list<string>

When defining APIs in Conjure, you can utilize standard HTTP abstractions to structure your service. These include:

• HTTP Methods: GET, PUT, POST, and DELETE.
• Query Parameters: Key-value pairs appended to the URL (e.g., ?foo=bar&baz=2).
• Path Parameters: Variable segments within a URL path (e.g., /repo/{owner}/{repo}/pulls/{id}).
• Headers: Non-case sensitive string names associated with Conjure values.
• Cookie auth: HTTP Cookies, typically used for authentication.

When deserializing JSON into Conjure types, follow these rules:

1. Handling null or absent keys:
   • If a key is absent or null, optional, list, set, and map types must be initialized to their empty variants.
   • Attempting to coerce null or an absent key to any other type (like string or integer) must result in an error.
2. No automatic casting:
   • Do not coerce types automatically. For example, if a field is defined as boolean, the JSON strings "true" or "false" must be rejected; only actual JSON booleans are valid.

Note: To avoid ambiguity, Conjure definitions do not allow the type optional<optional<T>>.