...

E.g. the URI https://sdp-v.services.cdc.gov/api/sections?limit=5&search=complications would return a JSON array of a maximum of 5 section representations, each of which include the word 'complications' in their name, description or tags.

Versioning

The SDP-V API has been versioned to add additional information but, since this would not affect existing clients, none of the versioning approaches described in the API guidance was yet neededFor some time, SDP-V supported tagging of various resources with coded concepts. These tags are included in resource representations as JSON arrays of objects, one object per tag, e.g.:

"tags": [
      {
        "code": "36989005",
        "system": "SCT",
        "display": "Mumps (disorder)"
      },
      {
        "code": "",
        "system": "",
        "display": "disease"
      }
    ]

In practice, users would include both coded concept tags but also simple string tags as shown above. End users and API clients requested that the two different usages be separated into a simpler string-based tagging system and a restructuring of the existing representation of coded concept tagging, ideally along the following lines:

"tags": [
      "mumps",
      "disease"
    ],
    "code_system_mapping": [
      {
        "code": "36989005",
        "system": "http://snomed.info/sct",
        "systemVersion": "20180926",
        "systemDisplayName": "SNOMED-CT",
        "displayName": "Mumps (disorder)"
      }
    ]

This kind of restructuring would represent a breaking change to the SDP-V API: API clients created prior to the change that were using the tags field of resource representations would encounter issues parsing the new structure. The following subsections describe each of the options that were considered and the approach that was decided upon.

Breaking Change

SDP-V is a relatively new service and there are only a few known API clients whose owners were requesting the breaking change described above.

Pros:

• Users requesting the change could be provided exactly what they requested
• No need to maintain two versions of the API (old and new representations)

Cons:

• Existing clients using the tags feature of the API would be broken
• The SDP-V team does not have a complete list of all existing clients so would be unable to notify owners of the change

Custom Media Type

SDP-V could use media type versioning to maintain the existing resource representation for existing clients and offer a new representation to new clients. SDP-V would default to using the existing representation unless the client requests the new representation using a HTTP Accept header that includes the new media type.

Pros:

• Users requesting the change could be provided exactly what they requested
• Existing clients would not be impacted

Cons:

• Need to maintain two versions of the API (old and new representations)
• Slightly more complex for new clients since they would need to include an HTTP Accept header in all requests

Non-breaking Change

SDP-V could add the new fields to the existing representation, renaming the new string-based tags field to avoid a name clash with the existing tags field. The representation would then include the following:

"tags": [
      {
        "code": "36989005",
        "system": "SCT",
        "display": "Mumps (disorder)"
      },
      {
        "code": "",
        "system": "",
        "display": "disease"
      }
    ],
    "simple_tags": [
      "mumps",
      "disease"
    ],
    "code_system_mapping": [
      {
        "code": "36989005",
        "system": "http://snomed.info/sct",
        "systemVersion": "20180926",
        "systemDisplayName": "SNOMED-CT",
        "displayName": "Mumps (disorder)"
      }
    ]

Pros:

• Users requesting the change could be provided the structure they requested, though with a different field name for the string-based tags
• Existing clients would not be impacted
• No need to maintain two versions of the API (old and new representations)

Cons:

• Tagging information is duplicated in two fields

This option was selected as the best balance of pros and cons.

API Definition

The SDP-V API is described using the Open API specification as recommended in the API guidance. An interactive page for exercising the API is provided using the Swagger tooling, the machine processable description is available at https://sdp-v.services.cdc.gov/api/vocab.yaml.