Skip to content

Conventions

British Spelling

The Rev79 API mostly uses British spelling for object/field names. Since the British are allergic to the letter "z", Americans may need to substitute "s" instead. For example: Organization => Organisation.

Mango Queries

The Rev79 GraphQL API allows you to filter/sort/limit result sets by providing a Mango Query. These can be provided to almost any list typed field as the query argument.

For example, this query will return the id of all projects named "Project A":

{
  projects(query: { selector: { name: "Project A" } }) {
    id
  }
}

When a value is provided, as above, a selector will filter using an equality match. To use another comparison you can provide an object with an appropriate key. This query will select all projects with an end date before the start of 2025:

query projectsBefore2025($selector: MangoSelector) {
  projects(query: { selector: $selector }) {
    id name startDate endDate
  }
}

{
  "selector": {
    "endDate": { "$lt": "2025-01-01" }
  }
}

Selection operators

Mango selectors are JSON objects specifying conditions which the returned record must match.

Warning

Operator names all start with a $, which the inline GraphQL object syntax does not permit in keys. Using any of these operators requires passing the condition in as a variable, either as a MangoSelector, or as a MangoQuery.

For object types, a selector must be an object. The keys of the object specify a "field path", with the values being a condition to apply to the value. For example, you could filter projects with the filter {"organisation.name": { "$regex": "abc" } } to select all projects belonging to organisations with "abc" (case insensitively) in their name. If multiple fields are provided, they are combined as if they had been provided as a list of single-key objects to $and.

For scalar fields the following operators are supported:

  • $lt: less than
  • $lte: less than or equal to
  • $eq: equal to
  • $ne: not equal to
  • $gte: greater than or equal to
  • $gt: greater than
  • $regex: case-insensitive regexp match
  • $in: equal to one of a list of elements
  • $nin: not equal to one of a list of elements

For list fields the following operators are supported:

  • $elemMatch: at least one element matches the provided condition
  • $all: all elements match the provided condition

Operators can also be combined using the following combinators:

  • $and: all of a list of conditions must match
  • $or: at least one of a list of conditions must match
  • $nor: all of a list of conditions must not match
  • $not: the condition must not match

Errors and Permissions

Warning

Error handling is a bit haphazard at the moment. There are some error cases which we don't yet have good error messages for. If you're getting HTTP 500s with no errors, let us know!

If your request is malformed then the server will respond with an error message with information on what was wrong with the request.

If you request a mutation for records you are not permitted to change then the server will respond with an error indicating which record(s) those are.

However, if you attempt to fetch records which you are not permitted to access then no error will be returned. Instead the server will filter out of the response any records you are not permitted to see. You may receive an empty list, not because the records do not exist, but because you are not permitted to see them.

Unstable fields

We endeavour to maintain backwards compatibility of the Rev79 API, to avoid breaking existing clients. However, sometimes we want to expose functionality without being sure of the best expression of that in our API. In order to do this, we have a concept of "unstable fields". These are fields for which we provide no broad guarantee of backwards compatibility, rather these are exposed for a particular client as we build out an idea.

To access unstable fields through the API, you can provide an includeUnstable query parameter to your request. The value should be a comma-separated list of unstable field categories that you would like exposed. Any unstable fields matching the categories requested will be exposed, while any other unstable fields will be unavailable (both to queries, and to introspection).

If you would like to list all unstable fields in the API, you can provide includeUnstable=true. Be warned, however, that Rev79 does not provide any guarantees about unstable fields. We reserve the right to change their behaviour, or even remove them entirely, at any time. If you are using an unstable field and would like some assurance that it will continue to work, please email the Rev79 team so we can work with you to stabilise it.

GraphQL to Internal Name Mappings

The Rev79 GraphQL API represents an idealised form of our underlying structure, but sometimes details from our ORM/database leak through. This is particularly an issue in error messages, which can be raised by a subsystem without appropriate translation.

To help mitigate the confusion this can cause, here is a list of the GraphQL types whose name differs from their corresponding internal type. We expect to improve on this over time, but in the meantime we hope this list helps with your debugging.

GraphQL Name Internal Name
Collaboration Assoc
CollaborationUser AssocPortfolioUser
Domain MarkerGroup
Funding Funder
FundingType FinanceType
GoalNumberIndicator OutputGoalTarget
GoalNumberIndicatorTarget ProjectTargetOutput
GoalProductionStage ProductGoalMarker
GoalProgressSchema GoalCommunity
GoalStrategicPriority GoalStrategy
GoalTitle GroupedTitle
GoalTitleGroup TitleGroup
ImpactPartner Team
ImpactTeam Team
LanguageEngagement FinishLineStatus
LanguageInfoNote LanguageInfoField
Narrative GoalProgress
OrganisationNationEngagement FinishLineStatus
OutcomeProgressAssessment CommunityOutcomeProgress
ProductionTarget ProjectTarget
ProgramPartner EngagementGroup
ProgressSchemaStatus TrackingStatus
Project Program
ProjectLanguageContact ProgramLanguageContact
ProjectMenuItem ProgramMenuItem
ProjectUser ProgramUser
ReportTemplate LearningTemplate
StandardNumberIndicator OutputMarker
StandardObjective FinishLineMarker
StandardProductSet ProductSet
StandardProductionStage ProductionMarker
StandardTitle Title
StandardTitleGroup TitleGroup
StrategicPriority Strategy
StrategicPriorityNote StrategyNote
StrategicPriorityResponsiblePerson StrategyUser
SuggestedEdit Edit
SuggestedEditComment CurationComment
UserPresence User
WorkDomain ProgramStream

Note that some internal names map to multiple GraphQL types, so there may still be some ambiguity in returned errors. If you run into error messages that you can't understand, get in touch with our development team and we can help.