{ "openapi": "3.0.1", "info": { "title": "QA 2.2 Linked Data API", "version": "2.2", "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" } }, "servers": [ { "url": "http://{site_host}/{apiBase}", "description": "QA v2.2 API Server", "variables": { "site_host": { "default": "localhost:3000", "description": "" }, "apiBase": { "default": "qa" } } } ], "paths": { "/list/linked_data/authorities": { "get": { "summary": "List currently loaded linked data authorities", "operationId": "GET_listAuthorities", "tags": [ "Authority Management" ], "responses": { "200": { "description": "Successfully accessed authority and received results.", "headers": { "Access-Control-Allow-Origin": { "description": "CORS header will be * if cors_headers_enabled", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/linked_data_authorities_list_result" } } } } } } }, "/reload/linked_data/authorities": { "get": { "summary": "Reload linked data authorities. Using this command avoids having to restart the rails server.", "operationId": "GET_reloadAuthorities", "tags": [ "Authority Management" ], "parameters": [ { "description": "Security token which must be included for this command to execute.", "in": "query", "name": "auth_token", "required": true, "schema": { "default": "", "type": "string" } } ], "responses": { "200": { "description": "Successfully reloaded authorities.", "headers": { "Access-Control-Allow-Origin": { "description": "CORS header will be * if cors_headers_enabled", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/linked_data_authorities_list_result" } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } } } } }, "/search/linked_data/{vocab}": { "get": { "summary": "Send a query string to an authority and return search results. Parameters are typical examples. Actual parameters are driven by the authority's config file.", "operationId": "GET_searchAuthority", "tags": [ "Search Query" ], "parameters": [ { "description": "Name of the authority's configuration file.", "in": "path", "name": "vocab", "required": true, "schema": { "default": "oclc_fast", "type": "string" } }, { "description": "The query string", "in": "query", "name": "q", "required": true, "schema": { "default": "science", "type": "string" } }, { "description": "Limit number of returned results. NOTE: Most authorities use maxRecords instead of maximumRecords for this parameter.", "in": "query", "name": "maximumRecords", "required": false, "schema": { "default": 4, "type": "integer" } }, { "description": "Limit string values to this language when multiple languages are provided.", "in": "query", "name": "lang", "required": false, "schema": { "default": "en", "type": "string" } } ], "responses": { "200": { "description": "Successfully accessed authority and received results.", "headers": { "Access-Control-Allow-Origin": { "description": "CORS header will be * if cors_headers_enabled", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/linked_data_query_results" } } } }, "400": { "description": "Bad Request - occurs when required params are missing (e.g. q)", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "500": { "description": "Internal Server Error - can be raised while attempting to access the external authority OR during processing of results when results are not a valid RDF Format", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "503": { "description": "Service Unavailable - can be raised while attempting to access the external authority", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } } } }, "options": { "summary": "CORS preflight request", "operationId": "OPTIONS_searchAuthority", "tags": [ "Search Query" ], "parameters": [ { "description": "Name of the authority's configuration file.", "in": "path", "name": "vocab", "required": true, "schema": { "default": "oclc_fast", "type": "string" } } ], "responses": { "204": { "description": "When CORS is enabled, perform CORS preflight for searching an authority", "headers": { "Access-Control-Allow-Origin": { "description": "CORS header will be * if CORS headers are enabled", "schema": { "type": "string" } }, "Access-Control-Allow-Methods": { "description": "Indicates which method a future CORS request to the same resource might use.", "schema": { "type": "string" } } }, "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "501": { "description": "OPTIONS action is not implement when CORS headers are not enabled", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } } } } }, "/search/linked_data/{vocab}/{subauthority}": { "get": { "summary": "Send a query string to a subauthority in an authority and return search results.", "operationId": "GET_searchSubauthority", "tags": [ "Search Query" ], "parameters": [ { "description": "Name of the authority's configuration file.", "in": "path", "name": "vocab", "required": true, "schema": { "default": "oclc_fast", "type": "string" } }, { "description": "Name of the subauthority.", "in": "path", "name": "subauthority", "required": true, "schema": { "default": "personal_name", "type": "string" } }, { "description": "The query string", "in": "query", "name": "q", "required": true, "schema": { "default": "twain", "type": "string" } }, { "description": "Limit number of returned results. NOTE: Most authorities use maxRecords instead of maximumRecords for this parameter.", "in": "query", "name": "maximumRecords", "required": false, "schema": { "default": 4, "type": "integer" } }, { "description": "Limit string values to this language when multiple languages are provided.", "in": "query", "name": "lang", "required": false, "schema": { "default": "en", "type": "string" } } ], "responses": { "200": { "description": "Successfully accessed subauthority in an authority and received results.", "headers": { "Access-Control-Allow-Origin": { "description": "CORS header will be * if CORS headers are enabled", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/linked_data_query_results" } } } }, "400": { "description": "Bad Request - occurs when required params are missing (e.g. q)", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "500": { "description": "Internal Server Error - can be raised while attempting to access the external authority OR during processing of results when results are not a valid RDF Format", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "503": { "description": "Service Unavailable - can be raised while attempting to access the external authority", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } } } }, "options": { "summary": "CORS preflight request", "operationId": "OPTIONS_searchSubauthority", "tags": [ "Search Query" ], "parameters": [ { "description": "Name of the authority's configuration file.", "in": "path", "name": "vocab", "required": true, "schema": { "default": "oclc_fast", "type": "string" } }, { "description": "Name of the subauthority.", "in": "path", "name": "subauthority", "required": true, "schema": { "default": "personal_name", "type": "string" } } ], "responses": { "204": { "description": "Perform CORS preflight for searching a subauthoroity in an authority", "headers": { "Access-Control-Allow-Origin": { "description": "CORS header will be * if CORS headers are enabled", "schema": { "type": "string" } }, "Access-Control-Allow-Methods": { "description": "Indicates which method a future CORS request to the same resource might use.", "schema": { "type": "string" } } }, "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "501": { "description": "OPTIONS action is not implement when CORS headers are not enabled", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } } } } }, "/show/linked_data/{vocab}/{id}": { "get": { "operationId": "GET_fetchByIDFromAuthority", "summary": "Get a single term from an authority. Generally there are no additional parameters. See the authority's configuration file to be sure. Some authorities support `lang` which can be used to filter the language of returned strings.", "tags": [ "Fetch Term" ], "parameters": [ { "description": "Name of the authority's configuration file.", "in": "path", "name": "vocab", "required": true, "schema": { "default": "oclc_fast", "type": "string" } }, { "description": "The ID or URI for the term being retrieved.", "in": "path", "name": "id", "required": true, "schema": { "default": "1914919", "type": "string" } }, { "description": "The format of the returned result.", "in": "query", "name": "format", "required": false, "schema": { "default": "json", "type": "string", "enum": [ "json", "jsonld" ] } } ], "responses": { "200": { "description": "Successfully accessed authority and received term.", "headers": { "Access-Control-Allow-Origin": { "description": "CORS header will be * if CORS headers are enabled", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/linked_data_term_json_result" } }, "application/ld+json": { "schema": { "$ref": "#/components/schemas/linked_data_term_jsonld_result" } } } }, "400": { "description": "Bad Request - occurs when required params are missing (e.g. id)", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "500": { "description": "Internal Server Error - can be raised while attempting to access the external authority OR during processing of results when results are not a valid RDF Format", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "503": { "description": "Service Unavailable - can be raised while attempting to access the external authority", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } } } }, "options": { "summary": "CORS preflight request", "operationId": "OPTIONS_fetchFromAuthority", "tags": [ "Fetch Term" ], "parameters": [ { "description": "Name of the authority's configuration file.", "in": "path", "name": "vocab", "required": true, "schema": { "default": "oclc_fast", "type": "string" } }, { "description": "The ID or URI for the term being retrieved.", "in": "path", "name": "id", "required": true, "schema": { "default": "1914919", "type": "string" } } ], "responses": { "204": { "description": "Perform CORS preflight for fetching a term from an authority", "headers": { "Access-Control-Allow-Origin": { "description": "CORS header will be * if CORS headers are enabled", "schema": { "type": "string" } }, "Access-Control-Allow-Methods": { "description": "Indicates which method a future CORS request to the same resource might use.", "schema": { "type": "string" } } }, "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "501": { "description": "OPTIONS action is not implement when CORS headers are not enabled", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } } } } }, "/show/linked_data/{vocab}/{subauthority}/{id}": { "get": { "operationId": "GET_fetchByIDFromSubauthority", "summary": "Get a single term from a subauthority in an authority. Generally there are no additional parameters. See the authority's configuration file to be sure. Some authorities support `lang` which can be used to filter the language of returned strings.", "tags": [ "Fetch Term" ], "parameters": [ { "description": "Name of the authority's configuration file.", "in": "path", "name": "vocab", "required": true, "schema": { "default": "loc", "type": "string" } }, { "description": "Name of the subauthority.", "in": "path", "name": "subauthority", "required": true, "schema": { "default": "names", "type": "string" } }, { "description": "The ID or URI for the term being retrieved.", "in": "path", "name": "id", "required": true, "schema": { "default": "n92016188", "type": "string" } }, { "description": "The format of the returned result.", "in": "query", "name": "format", "required": false, "schema": { "default": "json", "type": "string", "enum": [ "json", "jsonld" ] } } ], "responses": { "200": { "description": "Successfully accessed subauthority in the authority and received term.", "headers": { "Access-Control-Allow-Origin": { "description": "CORS header will be * if CORS headers are enabled", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/linked_data_term_json_result" } }, "application/ld+json": { "schema": { "$ref": "#/components/schemas/linked_data_term_jsonld_result" } } } }, "400": { "description": "Bad Request - occurs when required params are missing (e.g. id)", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "500": { "description": "Internal Server Error - can be raised while attempting to access the external authority OR during processing of results when results are not a valid RDF Format", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "503": { "description": "Service Unavailable - can be raised while attempting to access the external authority", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } } } }, "options": { "summary": "CORS preflight request", "operationId": "OPTIONS_fetchFromSubauthority", "tags": [ "Fetch Term" ], "parameters": [ { "description": "Name of the authority's configuration file.", "in": "path", "name": "vocab", "required": true, "schema": { "default": "loc", "type": "string" } }, { "description": "Name of the subauthority.", "in": "path", "name": "subauthority", "required": true, "schema": { "default": "names", "type": "string" } }, { "description": "The ID or URI for the term being retrieved.", "in": "path", "name": "id", "required": true, "schema": { "default": "n92016188", "type": "string" } } ], "responses": { "204": { "description": "Perform CORS preflight for fetching a term from a subauthority in an authority", "headers": { "Access-Control-Allow-Origin": { "description": "CORS header will be * if CORS headers are enabled", "schema": { "type": "string" } }, "Access-Control-Allow-Methods": { "description": "Indicates which method a future CORS request to the same resource might use.", "schema": { "type": "string" } } }, "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "501": { "description": "OPTIONS action is not implement when CORS headers are not enabled", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } } } } }, "/fetch/linked_data/{vocab}": { "get": { "operationId": "GET_fetchURIFromAuthority", "summary": "Get a single term from an authority given the term's URI. Generally there are no additional parameters. See the authority's configuration file to be sure. Some authorities support `lang` which can be used to filter the language of returned strings. NOTE: The authorities provided with QA do not support fetch by URI. See more authority configs at: https://github.com/LD4P/linked_data_authorities", "tags": [ "Fetch Term" ], "parameters": [ { "description": "Name of the authority's configuration file.", "in": "path", "name": "vocab", "required": true, "schema": { "default": "loc", "type": "string" } }, { "description": "The URI for the term being retrieved.", "in": "query", "name": "uri", "required": true, "schema": { "default": "http://id.loc.gov/authorities/genreForms/gf2011026141", "type": "string" } }, { "description": "The format of the returned result.", "in": "query", "name": "format", "required": false, "schema": { "default": "json", "type": "string", "enum": [ "json", "jsonld" ] } } ], "responses": { "200": { "description": "Successfully accessed authority and received term.", "headers": { "Access-Control-Allow-Origin": { "description": "CORS header will be * if CORS headers are enabled", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/linked_data_term_json_result" } }, "application/ld+json": { "schema": { "$ref": "#/components/schemas/linked_data_term_jsonld_result" } } } }, "400": { "description": "Bad Request - occurs when required params are missing (e.g. uri)", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "500": { "description": "Internal Server Error - can be raised while attempting to access the external authority OR during processing of results when results are not a valid RDF Format", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "503": { "description": "Service Unavailable - can be raised while attempting to access the external authority", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } } } }, "options": { "summary": "CORS preflight request", "operationId": "OPTIONS_fetchFromAuthority", "tags": [ "Fetch Term" ], "parameters": [ { "description": "Name of the authority's configuration file.", "in": "path", "name": "vocab", "required": true, "schema": { "default": "loc", "type": "string" } }, { "description": "The ID or URI for the term being retrieved.", "in": "path", "name": "id", "required": true, "schema": { "default": "http://id.loc.gov/authorities/genreForms/gf2011026141", "type": "string" } } ], "responses": { "204": { "description": "Perform CORS preflight for fetching a term from an authority", "headers": { "Access-Control-Allow-Origin": { "description": "CORS header will be * if CORS headers are enabled", "schema": { "type": "string" } }, "Access-Control-Allow-Methods": { "description": "Indicates which method a future CORS request to the same resource might use.", "schema": { "type": "string" } } }, "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "501": { "description": "OPTIONS action is not implement when CORS headers are not enabled", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } } } } }, "/fetch/linked_data/{vocab}/{subauthority}": { "get": { "operationId": "GET_fetchByURIFromSubauthority", "summary": "Get a single term from a subauthority in an authority given the term's URI. Generally there are no additional parameters. See the authority's configuration file to be sure. Some authorities support `lang` which can be used to filter the language of returned strings. NOTE: There currently aren't any authorities configured that support subauthorities and access terms using a URI instead of an ID. The default values in this example show what you might see but DO NOT WORK with the current LOC config.", "tags": [ "Fetch Term" ], "parameters": [ { "description": "Name of the authority's configuration file.", "in": "path", "name": "vocab", "required": true, "schema": { "default": "loc", "type": "string" } }, { "description": "Name of the subauthority.", "in": "path", "name": "subauthority", "required": true, "schema": { "default": "names", "type": "string" } }, { "description": "The URI for the term being retrieved.", "in": "query", "name": "uri", "required": true, "schema": { "default": "http://id.loc.gov/authorities/names/n92016188", "type": "string" } }, { "description": "The format of the returned result.", "in": "query", "name": "format", "required": false, "schema": { "default": "json", "type": "string", "enum": [ "json", "jsonld" ] } } ], "responses": { "200": { "description": "Successfully accessed subauthority in the authority and received term.", "headers": { "Access-Control-Allow-Origin": { "description": "CORS header will be * if CORS headers are enabled", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/linked_data_term_json_result" } }, "application/ld+json": { "schema": { "$ref": "#/components/schemas/linked_data_term_jsonld_result" } } } }, "400": { "description": "Bad Request - occurs when required params are missing (e.g. uri)", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "500": { "description": "Internal Server Error - can be raised while attempting to access the external authority OR during processing of results when results are not a valid RDF Format", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "503": { "description": "Service Unavailable - can be raised while attempting to access the external authority", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } } } }, "options": { "summary": "CORS preflight request", "operationId": "OPTIONS_fetchFromSubauthority", "tags": [ "Fetch Term" ], "parameters": [ { "description": "Name of the authority's configuration file.", "in": "path", "name": "vocab", "required": true, "schema": { "default": "loc", "type": "string" } }, { "description": "Name of the subauthority.", "in": "path", "name": "subauthority", "required": true, "schema": { "default": "names", "type": "string" } }, { "description": "The URI for the term being retrieved.", "in": "path", "name": "id", "required": true, "schema": { "default": "http://id.loc.gov/authorities/names/n92016188", "type": "string" } } ], "responses": { "204": { "description": "Perform CORS preflight for fetching a term from a subauthority in an authority", "headers": { "Access-Control-Allow-Origin": { "description": "CORS header will be * if CORS headers are enabled", "schema": { "type": "string" } }, "Access-Control-Allow-Methods": { "description": "Indicates which method a future CORS request to the same resource might use.", "schema": { "type": "string" } } }, "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } }, "501": { "description": "OPTIONS action is not implement when CORS headers are not enabled", "content": { "text/plain": { "schema": { "type": "string", "example": "" } } } } } } } }, "components": { "schemas": { "linked_data_authorities_list_result": { "type": "array", "items": { "type": "string" } }, "linked_data_query_results": { "type": "array", "items": { "required": [ "id", "uri", "label" ], "properties": { "id": { "type": "string" }, "uri": { "type": "string" }, "label": { "type": "string" }, "context": { "type": "object" } } } }, "linked_data_term_json_result": { "required": [ "id", "uri", "label" ], "properties": { "id": { "type": "string" }, "uri": { "type": "string" }, "label": { "type": "string" }, "altlabel": { "type": "array", "items": { "type": "string" } }, "broader": { "type": "array", "items": { "type": "string" } }, "narrower": { "type": "array", "items": { "type": "string" } }, "sameas": { "type": "array", "items": { "type": "string" } }, "predicates": { "type": "object", } } }, "linked_data_term_jsonld_result": { "required": [ "@context", "@graph" ], "properties": { "@context": { "type": "object" }, "@graph": { "type": "object" } } } } }, "tags": [ { "name": "Authority Management", "description": "Services managing all authorities." }, { "name": "Search Query", "description": "Services sending a search query to an authority to retrieve multiple results." }, { "name": "Fetch Term", "description": "Services to fetch a single term from an authority." } ] }