Add CRUD Endpoints for Dictionary References

[rosibaj]

• References can include scripts or code-lists
• Provide an update endpoint that can update only references from the api so you don't have to compile the whole dictionary.

[joneubank]

Spec Proposal

Create all 4 CRUD endpoints.

Get Reference

GET /dictionaries/{dictionaryId}/references/{pathToReference}

Get will return a single path from the references object.

This is a bit awkward compared to the other endpoints which allow interaction with multiple paths simultaneously, but since the cost of returning all references to look through is low this seems like the simplest interface for the consumer to get as wide or as narrow a view of the references as they need.

Path Parameters

Name	Description
dictionaryId	ID of the dictionary to read from
pathToReference	Could be empty (equivalent to #/), or a path to a reference (ex. /codeLists/regions). Do not include the # used in the schema, just the path.

Returns

A JSON object containing the references in the property data. For a string reference value this would look like:

{ "data": "Value of the reference" }

But if a nested object with references is at the specified path, this will return that nested value, for example a query on a hypothetical /codeLists path:

{
  "data": {
    "contactPreference": ["Phone", "Email", "House Call"],
    "emotion": ["Happy", "Sad", "Surprised", "Excited"],
    "responses": {
      "all": ["#/codeLists/responses/yesOrNo", "#/codeLists/responses/maybes"],
      "maybes": ["Maybe", "Not Sure", "I don't know"],
      "yesOrNo": ["Yes", "No"]
  }
}

If the reference is not found, will return a NotFoundError, status = 404.

Create References

POST /dictionaries/{dictionaryId}/references?preview={boolean}

This will create a new version of an existing dictionary with the provided references added. The new dictionary will have the same name and incremented minor version. If semantic versioning has been implemented, instead this should increment the patch version.

Path Parameters

Name	Description
dictionaryId	ID of the dictionary to update

Query Parameters

key	type	default	description
preview	boolean	false	Set to true to prevent any changes being saved. The output will validate that the request syntax is correct and if so output the same as if the changes were made, without the ID of the new dictionary. This will include the new dictionary version calculated by Lectern.

Body

JSON Object with the new content to insert into the dictionary's references. This may contain one or multiple reference values. It is required that all reference values in the input object are new. If any of the new input reference values alreadu exist the entire request will be rejected with no changes applied.

Example body with a single reference at #/codeLists/colours. This will add the reference colours to the existing path references/codeLists as long as there isn't an existing value at references/codeLists/colours.

{
  "codeLists": {
    "colours": ["White", "Blue", "Black", "Red", "Green"]
  }
}

Example body with multiple references along different paths. The values (of type string[] or string must be at paths with no existing values). The values that will be created here are codeLists/types/cards, codeLists/colours, and regex/cost.

{
  "codeLists": {
      "types": {
        "cards": ["Artifact", "Battle", "Creature", "Enchantment", "Instant", "Land", "Sorcery", "Planeswalker"]
      },
    "colours": ["White", "Blue", "Black", "Red", "Green"]
  },
  "regex": {
    "cost": "^({((([WUBRG]|([0-9]|[1-9][0-9]*))(\/[WUBRG])?)|(X)|([WUBRG](\/[WUBRG])?\/[P]))})+$"
  }
}

Returns

If successful: JSON object with the following properties of the new dictionary: name, version, and ID. ID is not included if preview=true.

On error, either:

• list of syntax errors in request - SyntaxError
• list of references in the request that already exist - BadRequestError
• dictionaryId not found - NotFoundError

Update References

PUT /dictionaries/{dictionaryId}/references?preview={boolean}
This will create a new version of an existing dictionary, updating the references provided. This will override reference values at the given paths, or create new reference value at any path that doesn't yet have a value.

The new dictionary will have the major value incremented since reference changes can invalidate existing data (breaking changes).
Stretch goal: check if the changes to the references include only new items added to arrays of values, if so, this can be a minor version increment (patch increment if semantic versioning is implemented). Additionally, check if the references changed are used in any of the schemas, if not, this can be a minor (or patch) increment since the changed values have not been used.

Path Parameters

Name	Description
dictionaryId	ID of the dictionary to update

Query Parameters

key	type	default	description
preview	boolean	false	Set to true to prevent any changes being saved. The output will validate that the request syntax is correct and if so output the same as if the changes were made, without the ID of the new dictionary. This will include the new dictionary version calculated by Lectern.

Body

JSON Object with the new content to update int the dictionary's references. This may contain one or multiple reference values. Since these changes will overwrite existing values, Lectern will validate the changes by attempting to resolve the references in schemas. If any modifications result in an invalid schema then the update will return with a list of the errors in the update.

See the Create Reference documentation for examples of body content. The structure is the same.

Returns

If successful: JSON object with the following properties of the new dictionary: name, version, and ID. ID is not included if preview=true.
On error, either:

• list of syntax errors in request - SyntaxError, status = 400
• dictionaryId not found - NotFoundError, status = 404

In the case that the request is properly formed but updating the requests cause the schemas to be invalid, you will receive a list of InvalidReference errors, status = 400

Delete Reference

DELETE /dictionaries/{dictionaryId}/references?preview={boolean}
Provided a list of paths in the body of this request, the references will be deleted from that path. Before committing the changes, lectern will validate that all references in the dictionary can still be resolved. If a reference that is used in a schema is in the list to be deleted then the request will be deleted.

Path Parameters

Name	Description
dictionaryId	ID of the dictionary to delete from

Query Parameters

key	type	default	description
preview	boolean	false	Set to true to prevent any changes being saved. The output will validate that the request syntax is correct and if so output the same as if the changes were made, without the ID of the new dictionary. This will include the new dictionary version calculated by Lectern.

Body

JSON array of the paths to delete.

Example with a list of references to delete.

["regex", "codeList/colours", "codeList/types/cards"]

Returns

If successful: JSON object with the following properties of the new dictionary: name, version, and ID. ID is not included if preview=true.
On error, either:

• list of syntax errors in request - SyntaxError, status = 400
• dictionaryId not found - NotFoundError, status = 404

In the case that the request is properly formed but deleting those references causes the schemas to be invalid, you will receive a list of InvalidReference errors, status = 400