Repository files navigation

Conjure is a simple but opinionated toolchain for defining APIs once and generating client/server interfaces in multiple languages.

Conjure was developed to help scale Palantir's microservice architecture - it has been battle-tested across hundreds of repos and has allowed devs to be productive in many languages.

Define your API once and then Conjure will generate idiomatic clients for Java, TypeScript, Python etc. The generated interfaces provide type-safe, clean abstractions so you can make network requests without worrying about the details.

For example in Java, Conjure interfaces allow you to build servers using existing Jersey compatible libraries like Dropwizard/Jetty.

See anexample below, or check out ourgetting started guide to define your first Conjure API.

• Enables teams to work together across many languages
• Eliminates an entire class of serialization bugs
• Abstracts away low-level details behind ergonomic interfaces
• Expressive language to model your domain (enums, union types, maps, lists, sets)
• Helps preserve backwards compatibility (old clients can talk to new servers)
• Supports incremental switchover from existing JSON/HTTP servers
• Zero config (works out of the box)

The Conjure compiler reads API definitions written in the concise,human-readable YML format and produces a JSON-basedintermediate representation (IR).

Conjure generators read IR and produce code in the target language. The associated libraries provide client and server implementations. Each generator is distributed as a CLI that conforms toRFC002:

Thegradle-conjurebuild tool is the recommended way of interacting with the Conjure ecosystem as it seamlessly orchestrates all the above tools. Alternatively, the compiler and generators may also be invokedmanually as they all behave in a consistent way (specified byRFC002).

Theconjure-verification tools allow Conjure generator authors to verify that their generators and libraries produce code that complies with thewire spec.

The following tools also operate on IR:

• conjure-postman - generatesPostmanCollections for interacting with Conjure defined APIs.
• conjure-backcompat - an experimental type checker that compares two IR definitions to evaluate whether they are wire format compatible (not yet open-sourced).

The following YAML file defines a simple Flight Search API. (Seeconcepts)

types:definitions:default-package:com.palantir.flightsearchobjects:Airport:alias:stringSearchRequest:fields:from:Airportto:Airporttime:datetimeSearchResult:alias:list<Connection>Connection:fields:from:Airportto:Airportnumber:stringservices:FlightSearchService:name:Flight Search Servicepackage:com.palantir.flightsearchbase-path:/flightsendpoints:search:docs:Returns the list of flight connections matching a given from/to/time request.http:POST /searchargs:request:SearchRequestreturns:SearchResultlist:docs:Returns flights departing from the given airport on the given day.http:GET /list/{airport}/{time}args:airport:Airporttime:datetimereturns:SearchResult

The following generated Java interface can be used on the client and the server.

packagecom.palantir.flightsearch;...@Consumes(MediaType.APPLICATION_JSON)@Produces(MediaType.APPLICATION_JSON)@Path("/")@Generated("com.palantir.conjure.java.services.JerseyServiceGenerator")publicinterfaceFlightSearchService {/** Returns the list of flight connections matching a given from/to/time request. */@POST@Path("flights/search")SearchResultsearch(SearchRequestrequest);/** Returns flights departing from the given airport on the given day. */@GET@Path("flights/list/{airport}/{time}")SearchResultlist(@PathParameter("airport")Airportairport,@PathParameter("time")OffsetDateTimetime);}

Type-safe network calls to this API can made from TypeScript as follows:

functiondemo():Promise<SearchResult>{constrequest:ISearchRequest={from:"LHR",to:"JFK",number:"BA117"};returnnewFlightSearchService(bridge).search(request);}

See theCONTRIBUTING.md document.

This tooling is made available under theApache 2.0 License.