Skip to content

Latest commit

 

History

History
53 lines (41 loc) · 3.6 KB

concepts.md

File metadata and controls

53 lines (41 loc) · 3.6 KB
Raw

Concepts

Conjure offers the following abstractions to use when defining your APIs. To see the JSON representation of these types, see the Wire specification.

HTTP endpoints

  • GET, PUT, POST, DELETE - HTTP methods.
  • Query parameters - e.g. https://example.com/api/something?foo=bar&baz=2
  • Path parameters - Parsed sections of URLs e.g. https://example.com/repo/{owner}/{repo}/pulls/{id}
  • Headers - A non-case sensitive string name associated with a Conjure value (see docs).
  • Cookie auth - A HTTP Cookie, often used for authentication.

Named types

Users may define the following kinds of named types. These can be referenced by their name elsewhere in a Conjure definition.

  • Object - a collection of named fields, each of which has their own Conjure type.
  • Enum - a type consisting of named string variants, e.g. "RED", "GREEN", "BLUE".
  • Alias - a named shorthand for another Conjure type, purely for readability.
  • Union - a type representing different named variants, each of which can contain different types. (Also known as 'algebraic data types' or 'tagged unions')

Container types

  • list<T> - an ordered sequence of items of type T.
  • map<K, V> - values of type V each indexed by a unique key of type K (keys are unordered).
  • optional<T> - represents a value of type T which is either present or not present.
  • set<T> - a collection of distinct values of type T.

Built-in types

  • any - a catch-all type which can represent arbitrary JSON including lists, maps, strings, numbers or booleans.
  • bearertoken - a string Json Web Token (JWT)
  • binary - a sequence of binary.
  • boolean - true or false
  • datetime - an ISO 8601 value e.g. 2018-07-25T10:20:32+01:00
  • double - a floating point number specified by IEEE 754, which includes NaN, +/-Infinity and signed zero.
  • integer - a signed 32-bit integer value ranging from -231 to 231 - 1.
  • rid - a Resource Identifier, e.g. ri.recipes.main.ingredient.1234
  • safelong - a signed 53-bit integer that can be safely represented by browsers without loss of precision, value ranges from -253 + 1 to 253 - 1
  • string - a sequence of UTF-8 characters
  • uuid - Universally Unique Identifier (aka guid) represented as a string

Opaque types

When migrating an existing API, it may be useful to use the following 'escape hatch' type. These are not recommended for normal APIs because Conjure can't introspect these external types to figure out what their JSON structure will be, so they're effectively opaque.

  • External Reference - a reference to a non-Conjure type, with an associated fallback Conjure type

Errors

Conjure allows defining named, structured errors so that clients can expect specific pieces of information on failure or handle entire categories of problems in one fell swoop.

  • Structured errors - have the following properties:
    • Name - a user chosen description of the error e.g. RecipeLocked
    • Namespace - a user chosen category of the error e.g. RecipeErrors
    • Code - one of the pre-defined categories.
    • Args - a map from string keys to Conjure types