openapi: 3.0.3 info: title: Atramhasis API version: 2.1.0 servers: - url: '/' paths: /conceptschemes/{scheme_id}/c: get: summary: Search for concepts or collections in a scheme. description: Search for concepts or collections in a scheme. tags: - Pyramid_skosprovider parameters: - name: scheme_id in: path description: The identifier for a certain concept scheme. required: true schema: type: string - name: type in: query description: Define if you want to show concepts or collections. Leave blank to show both. required: false schema: type: string - name: mode in: query description: Allows for special processing mode for dijitFilteringSelect. Makes it possible to use wildcards in the label parameter. required: false schema: type: string - name: label in: query description: Shows all concepts and collections that have this search string in one of their labels. required: false schema: type: string - name: collection in: query description: Get information about the content of a collection. Expects to be passed an id of a collection in this scheme. Will restrict the search to concepts or collections that are a member of this collection or a narrower concept of a member. required: false schema: type: string - name: sort in: query description: Define if you want to sort the results by a given field. Otherwise items are returned in an indeterminate order. Prefix with '+' to sort ascending, '-' to sort descending. eg. ``?sort=-label`` to sort all results descending by label. required: false schema: type: string - name: language in: query description: Returns the label with the corresponding language-tag if present. If the language is not present for this concept/collection, it falls back to 1) the default language of the provider. 2) 'en' 3) any label. Eg. ``?language=nl`` to show the dutch labels of the concepts/collections. required: false schema: type: string responses: 200: description: The concepts in this conceptscheme were found. content: application/json: schema: type: array items: $ref: '#/components/schemas/ConceptListItem' 404: description: The conceptscheme was not found. post: summary: Add a concept or collection to a conceptscheme. description: Add a concept or collection to a conceptscheme. The response body will contain a representation of the concept or collection after is has been added to the conceptscheme. tags: - Atramhasis parameters: - name: scheme_id in: path description: The identifier for a certain concept scheme. required: true schema: type: string requestBody: required: true description: Data to create concept or collection content: application/json: schema: $ref: "#/components/schemas/ConceptRequest" responses: 201: description: The concept or collection was added succesfully. content: application/json: schema: $ref: "#/components/schemas/ConceptResponse" 400: description: The concept or collection could not be added because the submitted json was invalid due to eg. validation errors. content: application/json: schema: $ref: "#/components/schemas/ValidationError" 404: description: The conceptscheme `scheme_id` does not exist. 405: description: The concept or collection could not be added because the conceptscheme `scheme_id` is a readonly conceptscheme. 500: $ref: "#/components/responses/Error" /conceptschemes/{scheme_id}/c/{c_id}: get: summary: Get information about a concept or collection. description: Get information about a concept or collection. tags: - Pyramid_skosprovider parameters: - name: scheme_id in: path description: The identifier for a certain concept scheme. required: true schema: type: string - name: c_id in: path description: The identifier for a certain concept or collection. required: true schema: type: integer responses: 200: description: The concept was found in the conceptscheme. content: application/json: schema: $ref: "#/components/schemas/ConceptResponse" 404: description: The concept was not found in the conceptscheme or the conceptscheme was not found. put: summary: Edit the concept or collection with id `c_id`. description: Edit the concept or collection with id `c_id`. The response body will contain a representation of the concept or collection after the modifications. tags: - Atramhasis parameters: - name: scheme_id in: path description: The identifier for a certain concept scheme. required: true schema: type: string - name: c_id in: path description: The identifier for a certain concept or collection. required: true schema: type: integer requestBody: required: true description: Data to create concept or collection content: application/json: schema: $ref: "#/components/schemas/ConceptRequest" responses: 200: description: The concept or collection was edited succesfully. content: application/json: schema: $ref: "#/components/schemas/ConceptResponse" 400: description: The concept or collection could not be edited because the submitted json was invalid due to eg. validation errors. content: application/json: schema: $ref: "#/components/schemas/ValidationError" 404: description: The conceptscheme `scheme_id` or the concept or collection `c_id` does not exist. 405: description: The concept or collection could not be edited because the conceptscheme `scheme_id` is a readonly conceptscheme. 500: $ref: "#/components/responses/Error" delete: summary: Remove the concept with id `c_id`. description: Remove the concept with id `c_id`. The response body will contain the last representation known by the service. tags: - Atramhasis parameters: - name: scheme_id in: path description: The identifier for a certain concept scheme. required: true schema: type: string - name: c_id in: path description: The identifier for a certain concept or collection. required: true schema: type: integer responses: 200: description: The concept or collection was deleted succesfully. content: application/json: schema: $ref: "#/components/schemas/ConceptResponse" 400: description: The concept or collection could not be deleted because the submitted json was invalid due to eg. validation errors. content: application/json: schema: $ref: "#/components/schemas/ValidationError" 404: description: The conceptscheme `scheme_id` or the concept or collection `c_id` does not exist. 405: description: The concept or collection could not be deleted because the conceptscheme `scheme_id` is a readonly conceptscheme. 409: description: The concept or collection could not be deleted because Atramhasis has determined that it's still being used somewhere else. The response body will contain a message and a list of :term:`URI`'s that are using this concept. 500: $ref: "#/components/responses/Error" /conceptschemes/{scheme_id}/tree: get: summary: Display a tree of a conceptscheme and its children description: List all languages known to this Atramhasis instance. tags: - Pyramid_skosprovider parameters: - name: scheme_id in: path description: The identifier for a certain concept scheme. required: true schema: type: string responses: 200: description: A tree view of the conceptscheme was returned. content: application/json: schema: type: array items: $ref: "#/components/schemas/ConceptTree" /conceptschemes/{scheme_id}: get: summary: Get information about a concept scheme. description: Get information about a concept scheme. tags: - Pyramid_skosprovider parameters: - name: scheme_id in: path description: The identifier for a certain concept scheme. required: true schema: type: string responses: 200: description: The conceptscheme was not found. content: application/json: schema: $ref: "#/components/schemas/ResponseConceptScheme" put: summary: Edit the conceptschemes description: Edit the conceptschemes with scheme_id. The response body will contain a representation of the conceptscheme. tags: - Pyramid_skosprovider parameters: - name: scheme_id in: path description: The identifier for a certain conceptscheme. required: true schema: type: string requestBody: required: true description: Data to alter the conceptscheme content: application/json: schema: $ref: "#/components/schemas/RequestConceptScheme" responses: 200: description: The concept or collection was edited succesfully. content: application/json: schema: $ref: "#/components/schemas/ResponseConceptScheme" 400: description: The conceptscheme could not be edited because the submitted json was invalid due to eg. validation errors. content: application/json: schema: $ref: "#/components/schemas/ValidationError" 404: description: The conceptscheme with `scheme_id` does not exist. 500: $ref: "#/components/responses/Error" /conceptschemes: get: summary: Get all registered conceptschemes. description: Get all registered conceptschemes. tags: - Pyramid_skosprovider responses: 200: description: The list of conceptschemes was found. content: application/json: schema: type: array items: $ref: "#/components/schemas/ConceptSchemeListItem" /languages: get: summary: List all languages known to this Atramhasis instance. description: List all languages known to this Atramhasis instance. tags: - Atramhasis parameters: - name: sort in: query description: Which field to sort on. Use `-` and `+` to indicate sort order. Eg. `id` or `+id` sort ascending on `id`, `-name` sort descending on `name`. required: false schema: type: string responses: 200: description: The list of languages was returned. content: application/json: schema: type: array items: $ref: "#/components/schemas/Language" /languages/{l_id}: get: summary: Get information on a certain language. description: Get information on a certain language. tags: - Atramhasis parameters: - name: l_id in: path description: The identifier for a certain language. required: true schema: type: string responses: 200: description: The language was found. content: application/json: schema: $ref: "#/components/schemas/Language" 404: description: The language was not found in this instance. put: summary: Edit or create language description: Update the information on a certain language or create an entry for a new one. tags: - Atramhasis parameters: - name: l_id in: path description: The identifier for a certain language. required: true schema: type: string requestBody: required: true description: Data to create or edit language content: application/json: schema: $ref: "#/components/schemas/Language" responses: 200: description: The language was updated or added. content: application/json: schema: $ref: "#/components/schemas/Language" 400: description: The request could not be executed because of problems with the submitted data. Most likely you are submitting an invalid IANA langage code. content: application/json: schema: $ref: "#/components/schemas/ValidationError" delete: summary: Delete language description: Delete a language from this Atramhasis instance. tags: - Atramhasis parameters: - name: l_id in: path description: The identifier for a certain language. required: true schema: type: string responses: 200: description: The language was deleted. content: application/json: schema: $ref: "#/components/schemas/Language" 404: description: The language was not found in this instance. /labeltypes: get: summary: Get labeltypes. description: Get labeltypes. tags: - Lists responses: 200: description: The labeltypes were found. content: application/json: schema: type: array items: $ref: "#/components/schemas/Type" /notetypes: get: summary: Get notetypes. description: Get notetypes. tags: - Lists parameters: - name: l_id in: path description: The identifier for a certain language. required: true schema: type: string responses: 200: description: The notetypes were found. content: application/json: schema: type: array items: $ref: "#/components/schemas/Type" /uris: get: summary: Look up where a certain URI can be found. description: Find more information on a certain :term:`URI`. This can map to eiter a concept, collection or conceptscheme that is known by the current SKOS registry. tags: - Pyramid_skosprovider parameters: - name: uri in: query description: The URI to search for. required: true schema: type: string responses: 200: description: The URI maps to something known by pyramid_skosprovider, either a conceptscheme, a concept or collection. content: application/json: schema: type: object properties: context: $ref: '#/components/schemas/Context' type: type: string uri: type: string id: type: integer concept_scheme: $ref: '#/components/schemas/ConceptSchemeLimited' 404: description: The URI can't be found by pyramid_skosprovider. /c: get: summary: Search concepts or collections. description: Search for concepts or collections, no matter what scheme they're a part of. tags: - Pyramid_skosprovider parameters: - name: type in: query description: Define if you want to show concepts or collections. Leave blank to show both. required: false schema: type: string - name: mode in: query description: Allows for special processing mode for dijitFilteringSelect. Makes it possible to use wildcards in the label parameter. required: false schema: type: string - name: label in: query description: Shows all concepts and collections that have this search string in one of their labels. required: false schema: type: string - name: language in: query description: Returns the label with the corresponding language-tag if present. If the language is not present for this concept/collection, it falls back to 1) the default language of the provider. 2) 'en' 3) any label. Eg. ``?language=nl`` to show the dutch labels of the concepts/collections. required: false schema: type: string - name: sort in: query description: Define if you want to sort the results by a given field. Otherwise items are returned in an indeterminate order. Prefix with '+' to sort ascending, '-' to sort descending. eg. ``?sort=-label`` to sort all results descending by label. required: false schema: type: string - name: providers.ids in: query description: A comma separated list of concept scheme id's. The query will only be passed to the providers with these id's. eg. ``?providers.ids=TREES, PARROTS`` will only list concepts from these two providers. required: false schema: type: string - name: providers.subject in: query description: A subject can be registered with a skosprovider in the registry. Adding this search parameter means that the query will only be passed on to providers that have been tagged with this subject. Eg. ``?providers.subject=external`` to only query the providers that have been marked with the subject `external`. required: false schema: type: string responses: 200: description: The concepts in this conceptscheme were found. content: application/json: schema: type: array items: $ref: '#/components/schemas/ConceptListItem' /conceptschemes/{scheme_id}/topconcepts: get: summary: Get the top concepts in a scheme. description: Get all top concepts in a certain conceptscheme. These are all the concepts in the conceptscheme that have no broader concept. tags: - Pyramid_skosprovider parameters: - name: scheme_id in: path description: The identifier for a certain conceptscheme. required: true schema: type: string - name: language in: query description: Returns the label with the corresponding language-tag if present. If the language is not present for this concept/collection, it falls back to 1) the default language of the provider. 2) 'en' 3) any label. Eg. ``?language=nl`` to show the dutch labels of the concepts/collections. required: false schema: type: string responses: 200: description: The topconcepts in this conceptscheme were found. content: application/json: schema: type: array items: $ref: "#/components/schemas/ConceptListItem" 404: description: The conceptscheme was not found. /conceptschemes/{scheme_id}/displaytop: get: summary: Get the top of a display hierarchy. description: Get the top of a display hierarchy. Depending on the underlying provider this will be a list of Concepts and Collections. tags: - Pyramid_skosprovider parameters: - name: scheme_id in: path description: The identifier for a certain conceptscheme. required: true schema: type: string - name: language in: query description: Returns the label with the corresponding language-tag if present. If the language is not present for this concept/collection, it falls back to 1) the default language of the provider. 2) 'en' 3) any label. Eg. ``?language=nl`` to show the dutch labels of the concepts/collections. required: false schema: type: string responses: 200: description: The concepts and collections were found. content: application/json: schema: type: array items: $ref: "#/components/schemas/ConceptListItem" 404: description: The conceptscheme was not found. /conceptschemes/{scheme_id}/c/{c_id}/displaychildren: get: summary: Get the children for display purposes. description: Get a list of Collections and Concepts that should be displayed as children of this Concept or Collection. tags: - Pyramid_skosprovider parameters: - name: scheme_id in: path description: The identifier for a certain conceptscheme. required: true schema: type: string - name: c_id in: path description: The identifier for a certain concept or collection. required: true schema: type: integer - name: language in: query description: Returns the label with the corresponding language-tag if present. If the language is not present for this concept/collection, it falls back to 1) the default language of the provider. 2) 'en' 3) any label. Eg. ``?language=nl`` to show the dutch labels of the concepts/collections. required: false schema: type: string responses: 200: description: The concept was found in the conceptscheme. content: application/json: schema: type: array items: $ref: "#/components/schemas/ConceptListItem" 404: description: The concept was not found in the conceptscheme or the conceptscheme was not found. /conceptschemes/{scheme_id}/c/{c_id}/expand: get: summary: Expand a concept or collection to all it's narrower concepts. description: Expand a concept or collection to all it's narrower concepts. This method should recurse and also return narrower concepts of narrower concepts. If the id passed belongs to a :class:`skosprovider.skos.Concept`, the id of the concept itself should be include in the return value. If the id passed belongs to a :class:`skosprovider.skos.Collection`, the id of the collection itself must not be present in the return value In this case the return value includes all the member concepts and their narrower concepts. Returns A list of id's or :class:`HTTPNotFound` if the concept or collection doesn't exist. tags: - Pyramid_skosprovider parameters: - name: scheme_id in: path description: The identifier for a certain conceptscheme. required: true schema: type: string - name: c_id in: path description: The identifier for a certain concept or collection. required: true schema: type: integer responses: 200: description: The concept/collection was found in the conceptscheme. content: application/json: schema: type: array items: type: integer 404: description: The concept/collection was not found in the conceptscheme or the conceptscheme was not found. /providers: get: summary: Get all registered providers. description: Get all registered providers. parameters: - name: subject in: query description: A value to filter providers on their subject schema: type: string tags: - Atramhasis responses: 200: description: List of providers retrieved successfully content: application/json: schema: type: array items: $ref: "#/components/schemas/Provider" 4XX: description: Bad request. 5XX: description: Unexpected error. post: summary: Create a provider. description: Create a provider with a conceptscheme. tags: - Atramhasis requestBody: required: true description: Data to create provider. content: application/json: schema: $ref: "#/components/schemas/Provider" responses: 201: description: Provider created successfully content: application/json: schema: $ref: "#/components/schemas/Provider" 4XX: description: Bad request. 5XX: description: Unexpected error. /providers/{id}: parameters: - name: id in: path description: The identifier of the provider. required: true schema: type: string get: summary: Get a single provider. description: Get the details of a single provider. tags: - Atramhasis responses: 200: description: Provider retrieved successfully content: application/json: schema: $ref: "#/components/schemas/Provider" 4XX: description: Bad request. 5XX: description: Unexpected error. put: summary: Update a provider or create a new one if it does not exist. description: Update a provider or create a new one if it does not exist. tags: - Atramhasis requestBody: required: true description: Data to update a provider. content: application/json: schema: allOf: - $ref: "#/components/schemas/Provider" - type: object required: - id responses: 200: description: Provider updated successfully content: application/json: schema: $ref: "#/components/schemas/Provider" 201: description: Provider created successfully content: application/json: schema: $ref: "#/components/schemas/Provider" 4XX: description: Bad request. 5XX: description: Unexpected error. delete: summary: Delete a provider. description: Delete a provider. tags: - Atramhasis responses: 204: description: Provider deleted successfully 4XX: description: Bad request. 5XX: description: Unexpected error. components: schemas: Language: type: object properties: id: type: integer name: type: integer Type: type: object properties: key: type: string label: type: string Relatedconcept: type: object properties: id: type: integer Label: type: object properties: type: type: string language: type: string label: type: string Note: type: object properties: note: type: string type: type: string language: type: string Source: type: object properties: citation: type: string Concepts: type: array items: $ref: "#/components/schemas/Relatedconcept" MatchList: type: array items: type: string Matches: type: array items: type: object properties: broad: $ref: "#/components/schemas/MatchList" close: $ref: "#/components/schemas/MatchList" exact: $ref: "#/components/schemas/MatchList" narrow: $ref: "#/components/schemas/MatchList" related: $ref: "#/components/schemas/MatchList" ConceptRequest: type: object properties: id: type: integer type: type: string labels: type: array items: $ref: "#/components/schemas/Label" notes: type: array items: $ref: "#/components/schemas/Note" sources: type: array items: $ref: "#/components/schemas/Source" broader: $ref: "#/components/schemas/Concepts" narrower: $ref: "#/components/schemas/Concepts" related: $ref: "#/components/schemas/Concepts" members: $ref: "#/components/schemas/Concepts" member_of: $ref: "#/components/schemas/Concepts" subordinate_arrays: $ref: "#/components/schemas/Concepts" matches: $ref: "#/components/schemas/Matches" infer_concept_relations: type: boolean ConceptResponse: allOf: - $ref: '#/components/schemas/ConceptRequest' - type: object properties: id: type: integer uri: type: string ConceptTree: type: object properties: id: type: string concept_id: type: integer label: type: string children: type: array items: type: object properties: id: type: string concept_id: type: integer label: type: string children: type: array RequestConceptScheme: type: object properties: labels: type: array items: $ref: "#/components/schemas/Label" notes: type: array items: $ref: "#/components/schemas/Note" sources: type: array items: $ref: "#/components/schemas/Source" ResponseConceptScheme: allOf: - $ref: "#/components/schemas/RequestConceptScheme" - type: object properties: id: type: integer uri: type: string label: type: string languages: type: array items: $ref: "#/components/schemas/Language" Context: type: object properties: version: type: string dct: type: string skos: type: string iso-thes: type: string rdf: type: string rdfs: type: string void: type: string uri: type: string type: type: string id: type: string label: type: string concept: type: string collection: type: string subject: type: object properties: id: type: string type: type: string concept_scheme: type: object properties: id: type: string type: type: string ConceptSchemeListItem: type: object properties: context: $ref: "#/components/schemas/Context" type: type: string id: type: string uri: type: string label: type: string subject: type: array items: type: string ConceptSchemeLimited: type: object properties: type: type: string uri: type: string id: type: string ConceptListItem: type: object properties: type: type: string uri: type: string id: type: string label: type: string ValidationError: type: object required: - message - errors properties: message: type: string errors: type: string Provider: type: object properties: id: type: string nullable: true maxLength: 200 type: type: string nullable: true conceptscheme_uri: type: string maxLength: 200 nullable: false uri_pattern: type: string nullable: true pattern: .*%s.* maxLength: 200 default_language: type: string nullable: true maxLength: 100 subject: type: array nullable: true items: type: string maxLength: 50 force_display_language: type: string nullable: true maxLength: 20 id_generation_strategy: type: string nullable: true enum: - NUMERIC - GUID - MANUAL expand_strategy: type: string nullable: true enum: - recurse - visit metadata: type: object additionalProperties: true nullable: true required: - conceptscheme_uri - uri_pattern Error: type: object required: - message properties: field: nullable: true type: string message: nullable: true type: string exception: nullable: true type: string Errors: type: array items: $ref: "#/components/schemas/Error" responses: BadRequest: description: OpenAPI request/response validation failed content: application/json: schema: $ref: "#/components/schemas/ValidationError" Error: description: OpenAPI request/response validation failed content: application/json: schema: oneOf: - $ref: "#/components/schemas/Error" - $ref: "#/components/schemas/Errors" NotFound: description: Resource not found