-
-
Save workergnome/afe5b74cff8f1b4fb6490667cf6a4886 to your computer and use it in GitHub Desktop.
Getty Vocabs Reconciliation Open API Spec
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
{ | |
"openapi": "3.0.0", | |
"info": { | |
"title": "Getty Vocabularies Reconciliation Service for OpenRefine", | |
"description": "Reconciliation service implementing the OpenRefine reconciliation API", | |
"version": "1.1.0" | |
}, | |
"servers": [ | |
{ | |
"url": "https://staging-services.aws.getty.edu", | |
"description": "Staging instance" | |
}, | |
{ | |
"url": "https://services.getty.edu", | |
"description": "Main production instance" | |
} | |
], | |
"paths": { | |
"/vocab/reconcile": { | |
"get": { | |
"summary": "Endpoint for reconciliation service", | |
"description": "Functions as service query interface or service metadata generator", | |
"externalDocs": { | |
"description": "OpenRefine API documentation", | |
"url": "https://github.com/OpenRefine/OpenRefine/wiki/Reconciliation-Service-API" | |
}, | |
"parameters": [ | |
{ | |
"in": "query", | |
"name": "callback", | |
"description": "Callback parameter", | |
"required": false, | |
"schema": { | |
"type": "string" | |
} | |
}, | |
{ | |
"in": "query", | |
"name": "queries", | |
"description": "A call to the reconciliation service API", | |
"required": false, | |
"schema": { | |
"type": "string", | |
"additionalProperties": { | |
"$ref": "#/components/schemas/queries" | |
} | |
}, | |
"example": "{ | |
\"q0\": { | |
\"query\": \"rhyta\", | |
\"type\": \"/aat\" | |
}, | |
\"q1\": { | |
\"query\": \"vermeer\", | |
\"type\": \"/ulan\" | |
}, | |
\"q2\": { | |
\"query\": \"berlin\", | |
\"type\": \"/tgn\", | |
\"limit\": 10, | |
\"properties\": [ | |
{ | |
\"p\": \"place type\", | |
\"pid\": \"placeType\", | |
\"v\": \"inhabited places\" | |
}, | |
{ | |
\"p\": \"broader place\", | |
\"pid\": \"broaderExt\", | |
\"v\": \"Germany\" | |
} | |
] | |
}, | |
\"q3\": { | |
\"query\": \"white\", | |
\"limit\": 25 | |
} | |
}" | |
} | |
], | |
"responses": { | |
"200": { | |
"description": "JSON literal object respose to reconciliation query parameters", | |
"content": { | |
"application/json": { | |
"schema": { | |
"$ref": "#/components/schemas/recon" | |
} | |
} | |
} | |
}, | |
"default": { | |
"description": "A JSON object with service descriptive information, used by the OpenRefine tool to set parameters needed for reconciliation functionality", | |
"content": { | |
"application/json": { | |
"schema": { | |
"$ref": "#/components/schemas/Callback" | |
} | |
} | |
} | |
} | |
} | |
}, | |
"post": { | |
"summary": "Endpoint for OpenRefine tool", | |
"description": "Main interface for OpenRefine query functionality", | |
"externalDocs": { | |
"description": "OpenRefine API documentation", | |
"url": "https://github.com/OpenRefine/OpenRefine/wiki/Reconciliation-Service-API" | |
}, | |
"parameters": [ | |
{ | |
"in": "query", | |
"name": "queries", | |
"description": "A call to the reconciliation service API", | |
"required": false, | |
"schema": { | |
"type": "string", | |
"additionalProperties": { | |
"$ref": "#/components/schemas/queries" | |
} | |
}, | |
"example": "{ | |
\"q0\": { | |
\"query\": \"rhyta\", | |
\"type\": \"/aat\" | |
}, | |
\"q1\": { | |
\"query\": \"vermeer\", | |
\"type\": \"/ulan\" | |
}, | |
\"q2\": { | |
\"query\": \"berlin\", | |
\"type\": \"/tgn\", | |
\"limit\": 10, | |
\"properties\": [ | |
{ | |
\"p\": \"place type\", | |
\"pid\": \"placeType\", | |
\"v\": \"inhabited places\" | |
}, | |
{ | |
\"p\": \"broader place\", | |
\"pid\": \"broaderExt\", | |
\"v\": \"Germany\" | |
} | |
] | |
}, | |
\"q3\": { | |
\"query\": \"white\", | |
\"limit\": 25 | |
} | |
}" | |
} | |
], | |
"responses": { | |
"200": { | |
"description": "JSON literal object respose to reconciliation query parameters", | |
"content": { | |
"application/json": { | |
"schema": { | |
"$ref": "#/components/schemas/recon" | |
} | |
} | |
} | |
}, | |
"default": { | |
"description": "A JSON object with service descriptive information, used by the OpenRefine tool to set parameters needed for reconciliation functionality", | |
"content": { | |
"application/json": { | |
"schema": { | |
"$ref": "#/components/schemas/Callback" | |
} | |
} | |
} | |
} | |
} | |
} | |
} | |
}, | |
"components": { | |
"schemas": { | |
"queries": { | |
"description": "Query request for reconcilication endpoint", | |
"type": "object", | |
"additionalProperties": { | |
"type": "object", | |
"description": "JSON object containing query values, types and limit. Key value can be any arbitrary string.", | |
"properties": { | |
"query": { | |
"type": "string", | |
"description": "A string to search for", | |
"example": "Berlin" | |
}, | |
"limit": { | |
"type": "integer", | |
"description": "An integer to specify how many results to return", | |
"example": 10 | |
}, | |
"type": { | |
"type": "string", | |
"description": "A single string, or an array of strings, specifying the types of result", | |
"enum": [ "/ulan", "/aat", "/tgn", "/all" ], | |
"example": "/tgn" | |
}, | |
"properties": { | |
"type": "array", | |
"description": "Array of json object literals with info on each property to use with search", | |
"items": { | |
"type": "object", | |
"properties": { | |
"p": { | |
"type": "string", | |
"description": "property name", | |
"example": "broader place" | |
}, | |
"pid": { | |
"type": "string", | |
"description": "property id", | |
"example": "broaderExt" | |
}, | |
"v": { | |
"type": "string", | |
"description": "string literal of property value", | |
"example": "Germany" | |
} | |
} | |
} | |
} | |
} | |
} | |
}, | |
"recon": { | |
"description": "JSON object containing results of query for a given identifier", | |
"type": "object", | |
"properties": { | |
"randomQueryKey": { | |
"type": "object", | |
"description": "JSON object containing search results", | |
"example": "q0", | |
"properties": { | |
"result": { | |
"type": "array", | |
"description": "Array of JSON objects with query results", | |
"items": { | |
"type": "object", | |
"properties": { | |
"id": { | |
"type": "string", | |
"description": "ID and type (AAT, TGN, ULAN) of query result", | |
"example": "aat/300198841" | |
}, | |
"name": { | |
"type": "string", | |
"description": "Display label for record", | |
"example": "rhyta" | |
}, | |
"score": { | |
"type": "number", | |
"description": "Score generated by Elasticsearch search algorithm", | |
"example": 20.340694 | |
}, | |
"match": { | |
"type": "boolean", | |
"description": "Boolean value indicating auto-match (not implemented)", | |
"example": false | |
}, | |
"type": { | |
"type": "array", | |
"description": "Available types the service can query", | |
"items": { | |
"type": "object", | |
"properties": { | |
"id": { | |
"type": "string", | |
"description": "Type identifier", | |
"enum": [ "/ulan", "/aat", "/tgn", "/all" ], | |
"example": "/aat" | |
}, | |
"name": { | |
"type": "string", | |
"description": "Type descriptive text", | |
"example": "AAT search" | |
} | |
} | |
} | |
} | |
} | |
} | |
} | |
} | |
} | |
} | |
}, | |
"Callback": { | |
"type": "object", | |
"properties": { | |
"name": { | |
"type": "string", | |
"description": "The name of the service, which will be used to display the service in the reconciliation menu", | |
"example": "Getty Vocabularies Reconciliation Service" | |
}, | |
"identifierSpace": { | |
"type": "string", | |
"format": "uri", | |
"description": "An URI for the type of identifiers returned by the service", | |
"example": "http://vocab.getty.edu/doc/#GVP_URLs_and_Prefixes" | |
}, | |
"schemaSpace": { | |
"type": "string", | |
"format": "uri", | |
"description": "An URI for the type of types understood by the service", | |
"example": "http://vocab.getty.edu/doc/#The_Getty_Vocabularies_and_LOD" | |
}, | |
"view": { | |
"type": "object", | |
"description": "An object with a template URL to view a given item from its identifier", | |
"properties": { | |
"url": { | |
"type": "string", | |
"format": "uri", | |
"description": "Template URL", | |
"example": "http://vocab.getty.edu/page/{{id}}" | |
} | |
} | |
}, | |
"defaultTypes": { | |
"type": "array", | |
"description": "List of different types that can be queried by the service", | |
"items": { | |
"type": "object", | |
"properties": { | |
"id": { | |
"type": "string", | |
"description": "Search type identifier", | |
"enum": [ "/ulan", "/aat", "/tgn", "/all" ], | |
"example": "/aat" | |
}, | |
"name": { | |
"type": "string", | |
"description": "Search type description", | |
"example": "AAT search" | |
} | |
} | |
} | |
}, | |
"preview": { | |
"type": "object", | |
"description": "Parameters needed for recon service preview API", | |
"properties": { | |
"url": { | |
"type": "string", | |
"format": "uri", | |
"description": "Templated path for recon preview API", | |
"example": "http://services.getty.edu/vocab/reconcile/preview?id={{id}}" | |
}, | |
"height": { | |
"type": "integer", | |
"description": "Height of the iFrame that will render the preview HTML", | |
"example": 200 | |
}, | |
"width": { | |
"type": "integer", | |
"description": "Width of the iFrame that will render the preview HTML", | |
"example": 350 | |
} | |
} | |
}, | |
"suggest": { | |
"type": "object", | |
"description": "Parameters needed for recon service property suggest API", | |
"properties": { | |
"property": { | |
"type": "object", | |
"description": "Parameters for property suggest function", | |
"properties": { | |
"service_path": { | |
"type": "string", | |
"description": "Route for property suggest service", | |
"example": "/suggest/property" | |
}, | |
"service_url": { | |
"type": "string", | |
"format": "uri", | |
"description": "Base URL for property suggest service", | |
"example": "http://services.getty.edu/vocab/reconcile" | |
} | |
} | |
} | |
} | |
} | |
} | |
} | |
}, | |
"examples": { | |
"queries": { | |
"value": { | |
"q0": { | |
"query": "rhyta", | |
"type": "/aat" | |
}, | |
"q1": { | |
"query": "vermeer", | |
"type": "/ulan" | |
}, | |
"q2": { | |
"query": "berlin", | |
"type": "/tgn", | |
"limit": 10, | |
"properties": [ | |
{ | |
"p": "place type", | |
"pid": "placeType", | |
"v": "inhabited places" | |
}, | |
{ | |
"p": "broader place", | |
"pid": "broaderExt", | |
"v": "Germany" | |
} | |
] | |
}, | |
"q3": { | |
"query": "white", | |
"limit": 25 | |
} | |
} | |
} | |
} | |
} | |
} |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment