prosoprAPhI.yaml

swagger: "2.0"

info:
  version: 0.1.0
  title: prosopogrAPhI
  description: basic prosopographical data API
  # contact: georg.vogeler@uni-graz.at
  # licence 

schemes:
  - https
  - http
#host: www.cei.lmu.de
#basePath: /prosopographi/api.0.1
host: localhost
basePath: "/api"
produces:
  - application/json
  - text/xml
  
paths:

  /factoids:
    get:
      summary: Gets factoids
      description: Gets an array of `Factoid` objects. 
                   The number of array members returned with each response is restricted by the **size** parameter. 
                   Factoids can be filtered by setting additional parameters like **p_id** or **p**. TODO Further 
                   parameters for filtering have to be specified.
      parameters:
        - $ref: "#/parameters/size"
        - $ref: "#/parameters/page"
        - $ref: "#/parameters/sort_by"
        - $ref: "#/parameters/p_id"
        - $ref: "#/parameters/p"
        - $ref: "#/parameters/st_id"
        - $ref: "#/parameters/st"
        - $ref: "#/parameters/s_id"
        - $ref: "#/parameters/s"
        - $ref: "#/parameters/f"
      responses:
        200:
          description: A list of Factoids
          schema:
            type: array
            items:
              $ref: "#/definitions/Factoid"
        400:
          $ref: "#/responses/BadRequestError"
        500:
          $ref: "#/responses/Standard500ErrorResponse"
    head:
      summary: Gets metadata about factoids
      description: Uses the same filtering parameters as GET, but does not return any results, but metadata like the number of factoids etc.
                   TODO *I'm not sure if we really need this and what metadata will be useful beside the totel number of
                   available factoids*
                   TODO *Possibly this could replace the describe uris?*
      parameters:
        - $ref: "#/parameters/p_id"
        - $ref: "#/parameters/p"
      responses:
        200:
          description: Metadata about the factoids to be returned. *TODO schema has to to be discussed*
#          schema:
#            type: array
#            items:
#              $ref: "#/definitions/Factoid"
        400:
          $ref: "#/responses/BadRequestError"
        500:
          $ref: "#/responses/Standard500ErrorResponse"          
    post:
      # ToDo: Authentication!
      summary: creates a factoid
      parameters:
        - name: factoid
          in: body
          description: the factoid
          schema:
            $ref: "#/definitions/Factoid"
      responses:
        201:
          description: factoid created
          #Should return the id of the factoid created
        400:
          description: factoid could not be created or updated
        403:
          description: Forbidden. Missing token or user is not allowed to create persons. 
        500:
          $ref: "#/responses/Standard500ErrorResponse"
        501:
          $ref: "#/responses/NotImplementedError"
          
          
          
  /factoids/{id}:
    get:
      summary: gets the factoid with the {id}
      parameters:
        - $ref: "#/parameters/id"
      responses:
        200:
          description: a factoid
          schema:
            $ref: "#/definitions/Factoid"
        404:
          description: the factoid does not exist
        500:
          $ref: "#/responses/Standard500ErrorResponse"
# Gunv: POST is not needed here. To force creating a specific id for a resource can be done using put on a non existing
# resource. 
#    post:
#      # ToDo: Authentication!
#      summary: creates the factoid with the {id}
#      parameters:
#        - name: id
#          in: path
#          required: true
#          type: string
#        - name: content
#          in: body
#          schema:
#            $ref: "#/definitions/Factoid"
#      responses:
#        201:
#          description: factoid updated or created
#        400:
#          description: factoid could not be updated or created
#        500:
#          $ref: "#/responses/Standard500ErrorResponse"
#        501:
#          $ref: "#/responses/NotImplementedError"
    put:
      # ToDo: Authentication!
      summary: updates the factoid with the {id}
      parameters:
        - $ref: "#/parameters/id"      
        - name: content
          in: body
          schema:
            $ref: "#/definitions/Factoid"
      responses:
        201:
          description: factoid updated
        400:
          description: factoid could not be updated or created. TODO should return reason as message
        403:
          description: Forbidden. Missing token or user is not allowed to create persons. 
        500:
          $ref: "#/responses/Standard500ErrorResponse"
        501:
          $ref: "#/responses/NotImplementedError"
#    patch:
#      description: TODO *I do not think patching factoids makes sense. Has to be discussed!*
#      parameters:
#        - $ref: "#/parameters/id"      
#        - name: content
#          in: body
#          schema:
#            title: part of a factoid
#        
#      responses:
#        501:
#          $ref: "#/responses/NotImplementedError"        
#          
          
          
  # ToDo: Which subpaths do we need, e.g.
  #  getting only the person, statement, source of factoid to enhance walk through?
  #  sort order? maybe as path
  
  
  /persons:
    get:
      summary: Get persons
      description: Gets a list of `Person` objects.
                   The number of array members returned with each response is restricted by the **size** parameter. 
                   Persons can be filtered by setting additional parameters like **f_id** or **f**. TODO Further 
                   parameters for filtering have to be specified.      
      parameters:
        - $ref: "#/parameters/size"
        - $ref: "#/parameters/page"
        - $ref: "#/parameters/sort_by"
        - $ref: "#/parameters/p"
        - $ref: "#/parameters/f_id"
        - $ref: "#/parameters/f"
        - $ref: "#/parameters/st_id"
        - $ref: "#/parameters/st"
        - $ref: "#/parameters/s_id"
        - $ref: "#/parameters/s"
      responses:
        200:
          description: Successfull response
          schema:
            title: Array of Person objects
            type: array
            items:
              $ref: "#/definitions/Person"
        400: 
          $ref: "#/responses/BadRequestError"
        500:
          $ref: "#/responses/Standard500ErrorResponse"
           
    head:
      summary: Get metadata about persons
      description: Uses the same filtering parameters as GET, but does not return any results, but metadata like the number of persons found etc.
                   TODO *I'm not sure if we really need this and what metadata will be useful beside the total number of
                   available persons*
                   TODO *Possibly this could replace the describe uris?*
      parameters:
        - $ref: "#/parameters/sort_by"
        - $ref: "#/parameters/f_id"
        - $ref: "#/parameters/f"
        - $ref: "#/parameters/st_id"
        - $ref: "#/parameters/st"
        - $ref: "#/parameters/s_id"
        - $ref: "#/parameters/s"
      responses:
        200:
          description: Metadata about the factoids to be returned. *TODO schema has to to be discussed*                      
        400:
          $ref: "#/responses/BadRequestError"
        500:
          $ref: "#/responses/Standard500ErrorResponse"                
    post:
      summary: Add a new person
      responses:
        201:
          description: Person created
          #FixMe: Should return the id of the created person or the whole person object?
          headers:
            Location: 
              description: the uri of the created person
              type: string
          schema:
            $ref: "#/definitions/Person"
        400:
          $ref: "#/responses/BadRequestError"
        403:
          description: Forbidden. Missing token or user is not allowed to create persons. 
        500:
          $ref: "#/responses/Standard500ErrorResponse"
        501:
          $ref: "#/responses/NotImplementedError"
          

  /persons/{id}:
    get:
      summary: gets the person with the {id}
      parameters:
        - $ref: "#/parameters/id"      
      responses:
        200:
          description: a person object
          schema:
            $ref: "#/definitions/Person"
        404:
          description: the person does not exist
        500:
          $ref: "#/responses/Standard500ErrorResponse"

    put:
      # ToDo: Authentication!
      summary: updates the person with the {id}
      parameters:
        - $ref: "#/parameters/id"      
        - name: content
          in: body
          schema:
            $ref: "#/definitions/Person"
      responses:
        201:
          description: person updated
        400:
          description: person could not be updated or created. TODO should return reason as message
        403:
          description: Forbidden. Missing token or user is not allowed to create persons. 
        500:
          $ref: "#/responses/Standard500ErrorResponse"
        501:
          $ref: "#/responses/NotImplementedError"
#    patch:
#      description: TODO *I do not think patching persons makes sense. Has to be discussed!*
#      parameters:
#        - $ref: "#/parameters/id"
#        - name: content
#          in: body
#          schema:
#            title: part of a person
#     
#      responses:
#        501:
#          $ref: "#/responses/NotImplementedError"        


          
  # Gunv: This should be part of factoids!
  #/persons/{id}/factoids:
  #  get:
  #    summary: get all factoids about the person with the {id}
  #    parameters:
  #      - $ref: "#/parameters/id"
  #    responses:
  #      200:
  #        description: a list of factoids
  #        schema:
  #          $ref: "#/definitions/Factoid"
  #      500:
  #        $ref: "#/responses/Standard500ErrorResponse"
  
  
  
  /sources:
    get:
      summary: gets a list of sources
      description: Gets a list of `Source` objects.
                   The number of array members returned with each response is restricted by the **size** parameter. 
                   Sources can be filtered by setting additional parameters like **f_id** or **f**. TODO Further 
                   parameters for filtering have to be specified.      
      parameters:
        - $ref: "#/parameters/size"
        - $ref: "#/parameters/page"
        - $ref: "#/parameters/sort_by"
        - $ref: "#/parameters/p_id"
        - $ref: "#/parameters/p"
        - $ref: "#/parameters/f_id"
        - $ref: "#/parameters/f"
        - $ref: "#/parameters/st"
      responses:
        200:
          description: Successfull response
          schema:
            title: Array of Source objects
            type: array
            items:
              $ref: "#/definitions/Source"
        400: 
          $ref: "#/responses/BadRequestError"
      
        500:
          $ref: "#/responses/Standard500ErrorResponse"
          
    head:
      summary: gets a list of sources
      description: Uses the same filtering parameters as GET, but does not return any results, but metadata like the number of sources found etc.
                   TODO *I'm not sure if we really need this and what metadata will be useful beside the totel number of
                   available sources*
                   TODO *Possibly this could replace the describe uris?*
      parameters:
        - $ref: "#/parameters/size"
        - $ref: "#/parameters/page"
        - $ref: "#/parameters/sort_by"
        - $ref: "#/parameters/p_id"
        - $ref: "#/parameters/f_id"
        - $ref: "#/parameters/f"
        - $ref: "#/parameters/st_id"
        - $ref: "#/parameters/st"
        - $ref: "#/parameters/p"
      responses:
        200:
          description: Metadata about the factoids to be returned. *TODO schema has to to be discussed*                      
        400:
          $ref: "#/responses/BadRequestError"
        500:
          $ref: "#/responses/Standard500ErrorResponse"                
    post:
      summary: Add a new source
      responses:
        201:
          description: Source created
          #FixMe: Should return the id of the created source or the whole source object?
          headers:
            Location: 
              description: the uri of the created source
              type: string
          schema:
            $ref: "#/definitions/Source"
        400:
          $ref: "#/responses/BadRequestError"
        403:
          description: Forbidden. Missing token or user is not allowed to create persons. 
        500:
          $ref: "#/responses/Standard500ErrorResponse"
        501:
          $ref: "#/responses/NotImplementedError"

          
  /source/{id}:
    get:
      summary: gets the source with the {id}
      parameters:
        - $ref: "#/parameters/id"
        
      responses:
        200:
          description: a source object
          schema:
            $ref: "#/definitions/Source"
        404:
          description: the source does not exist
        500:
          $ref: "#/responses/Standard500ErrorResponse"

    put:
      # ToDo: Authentication!
      summary: updates the source with the {id}
      parameters:
        - name: id
          in: path
          required: true
          type: string
        - name: metadata
          in: body
          schema:
            $ref: "#/definitions/Source"
      responses:
        201:
          description: source updated
        400:
          description: source could not be updated or created. TODO should return reason as message
        403:
          description: Forbidden. Missing token or user is not allowed to create sources. 
        500:
          $ref: "#/responses/Standard500ErrorResponse"
        501:
          $ref: "#/responses/NotImplementedError"
#    patch:
#      description: TODO *I do not think patching persons makes sense. Has to be discussed!*
#      parameters:
#        - name: id
#          in: path
#          required: true
#          type: string
#        - name: content
#          in: body
#          schema:
#            title: part of a source
#        
#      responses:
#        501:
#          $ref: "#/responses/NotImplementedError"        


  /statements:
    get:
      summary: gets a list of statements
      description: Gets a list of `Statement` objects.
                   The number of array members returned with each response is restricted by the **size** parameter. 
                   Statements can be filtered by setting additional parameters like **f_id** or **f**. TODO Further 
                   parameters for filtering have to be specified.      
      parameters:
        - $ref: "#/parameters/size"
        - $ref: "#/parameters/page"
        - $ref: "#/parameters/sort_by"
        - $ref: "#/parameters/p_id"
        - $ref: "#/parameters/f_id"
        - $ref: "#/parameters/f"
        - $ref: "#/parameters/s_id"
        - $ref: "#/parameters/st"
        - $ref: "#/parameters/p"
      responses:
        200:
          description: Successfull response
          schema:
            title: Array of Statement objects
            type: array
            items:
              $ref: "#/definitions/Statement"
        400: 
          $ref: "#/responses/BadRequestError"
      
        500:
          $ref: "#/responses/Standard500ErrorResponse"
          
    head:
      summary: gets a list of statements
      description: Uses the same filtering parameters as GET, but does not return any results, but metadata like the number of statements 
                   found etc.
                   TODO *I'm not sure if we really need this and what metadata will be useful beside the totel number of
                   available sources*
                   TODO *Possibly this could replace the describe uris?*
      parameters:
        - $ref: "#/parameters/size"
        - $ref: "#/parameters/page"
        - $ref: "#/parameters/sort_by"
        - $ref: "#/parameters/p_id"
        - $ref: "#/parameters/f_id"
        - $ref: "#/parameters/f"
        - $ref: "#/parameters/s_id"
        - $ref: "#/parameters/s"
        - $ref: "#/parameters/p"
      responses:
        200:
          description: Metadata about the statements to be returned. *TODO schema has to to be discussed*                      
        400:
          $ref: "#/responses/BadRequestError"
        500:
          $ref: "#/responses/Standard500ErrorResponse"                
    post:
      summary: Add a new statement
      responses:
        201:
          description: Statement created
          #FixMe: Should return the id of the created source or the whole source object?
          headers:
            Location: 
              description: the uri of the created statement
              type: string
          schema:
            $ref: "#/definitions/Statement"
        400:
          $ref: "#/responses/BadRequestError"
        403:
          description: Forbidden. Missing token or user is not allowed to create statement. 
        500:
          $ref: "#/responses/Standard500ErrorResponse"
        501:
          $ref: "#/responses/NotImplementedError"

          
  /statement/{id}:
    get:
      summary: gets the statement with the {id}
      parameters:
        - $ref: "#/parameters/id"      
      responses:
        200:
          description: a statement object
          schema:
            $ref: "#/definitions/Statement"
        404:
          description: the statement does not exist
        500:
          $ref: "#/responses/Standard500ErrorResponse"

    put:
      # ToDo: Authentication!
      summary: updates the statement with the {id}
      parameters:
        - $ref: "#/parameters/id"      
        - name: content
          in: body
          schema:
            $ref: "#/definitions/Statement"
      responses:
        201:
          description: statement updated
        400:
          description: statement could not be updated or created. TODO should return reason as message
        403:
          description: Forbidden. Missing token or user is not allowed to create statements. 
        500:
          $ref: "#/responses/Standard500ErrorResponse"
        501:
          $ref: "#/responses/NotImplementedError"
#    patch:
#      description: TODO *I do not think patching statements makes sense. Has to be discussed!*
#      parameters:
#        - $ref: "#/parameters/id"      
#        - name: content
#          in: body
#          schema:
#            title: part of a statement
#        
#      responses:
#        501:
#          $ref: "#/responses/NotImplementedError"        


# Gunv search is handled via query parameter          
#  /sources/search:
#    #Do we need a "search" path, or can we replace it by ?q-Parameter?
#    get:
#      summary: full text search in all literal content of the source description
#      # ToDo: Or search in all factoids based on this source?
#      responses:
#        500:
#          $ref: "#/responses/Standard500ErrorResponse"
#  /search:
#    #Do we need a "search" path, or can we replace it by ?q-Parameter?
#    get:
#      summary: full text search in all literal content
#      responses:
#        500:
#          $ref: "#/responses/Standard500ErrorResponse"
  /describe:
    get:
      description: Gives basic information about schemas used, numbers of entries and implementation of API
             TODO *This could possibly be handled via HEAD request?* 
      responses:
        500:
          $ref: "#/responses/Standard500ErrorResponse"
  /describe/statement/schema:
    get:
      description: The schema used to describe the statements
      responses:
        200:
          description: "A URL pointing to the @context for the JSON-LD used in graph respones"
          schema:
            type: string
        500:
          $ref: "#/responses/Standard500ErrorResponse"
  /describe/return/schemas:
    get:
      description: The schemas supported by the server as return values
      responses:
        500:
          $ref: "#/responses/Standard500ErrorResponse"
  /describe/return/formats:
    get:
      description: The serialisations supported by the server for return values, default is JSON
      responses:
        #200:
        ## ToDo: give an enumarted list included default
        500:
          $ref: "#/responses/Standard500ErrorResponse"
  /describe/source/schema:
    get:
      description: The schema used to describe the source
      responses:
        200:
          description: "a URL pointing to the @context for the JSON-LD used in descriptions of sources"
          schema:
            type: string
        500:
          $ref: "#/responses/Standard500ErrorResponse"

definitions:
  Factoid:
    # FPO calls this "Ássertion" ?
    description: A Factoid is a composite of one or more statements about a person extracted by somebody from a source at a specific time
#    type: object
    # type: object    
    properties:
        id:
          $ref: "#/definitions/id"
        person:
          $ref: "#/definitions/Person"
        statement:
          $ref: "#/definitions/Statement"
        source:
          $ref: "#/definitions/Source"
        metadata:
          description: metadata describing the creation event of the factoid
#          type: object
          items:
            properties:
              createdBy:
                type: string
              createdWhen:
                type: string # date ? 
    example:
        - id: TW_Pez1_809_1 
          person: Andreas_Reuter
          statement: 
            - id: Pez1_809_1
              text: "Andreas Reuter (ca. 1648 Kremsmünster – 1715 Gleink) war Konventuale von Gleink. Er war Doktor der Theologie, apostolischer Protonotar und wirkte in Gleink als Ökonom sowie insgesamt 22 Jahre lang als Prior. Als solcher begegnet er 1708 als Unterzeichner der Rotel auf Abt Rupert von Kimpflern und 1710 in seinem Brief an Bernhard Pez."
          source: PezNachlassVol1
          metadata:
            createdBy: Thomas Wallnig
            createdWhen: 2010
        - id: TW_Pez1_123456
          person: Placidus_Seiz
          statement: 
            - id: "Pez#474-7"
              text: "... , quam accepturum me spero a reverendissimo domino abbate Ettalensi ..."
          source: "Pez#474"
          metadata:
            createdBy: Thomas Wallnig
            createdWhen: 2007-04-16
        - id: TW_Pez1_123456
          person: Placidus_Seiz
          statement: 
            - graph:
              - "@context" : "http://pez-digital.at/prosopography-schema.json-ld"
                "@graph": 
                  - "@id" : "http://pez-digital.at/Lindner-Album_Ettalense253f"
                    "assignedTo" : 
                      - "@id" : "http://pez-digital.at/placidus_Seiz"
                    "hasName" :  
                      - "@value" : "Placidus Seitz"
          source: "Lindner-Album_Ettalense253f."
          metadata:
            createdBy: Thomas Wallnig
            createdWhen: 2007-04-16
  Person:
    description: A Person is an abstract entity representing a human individual (fictional or historical) independet from their cultural desciption by name, status, social relationsships etc. It has therefore only formal identifiers as properties.
    properties:
      id:
        $ref: "#/definitions/id"
      uri:
        $ref: "#/definitions/uri"
      sameAs:
        $ref: "#/definitions/sameAs"
    example:
      - id: Andreas_Reuter
      - uri: "http://pezdigital/persons#Mauro_Aspini"
      - id: Placidus_Seiz
        sameAs: 
          http://d-nb.info/gnd/10102407X
          https://viaf.org/viaf/5285530/
  Statement:
    # FPO calls this factoid?
    properties:
      id:
        $ref: "#/definitions/id"
      text:
        type: string
      graph:
        description: "The object describing representing the statement as a graph follwos these rules: 
          1. Every path possible in the graph has to be linked to the person described by the factoid via steps explicitly expressed in the graph.
          2. All types and properties used in the graph can be mapped to a superclass taken from the CIDOC-CRM. These relationships are formaly described as a schema which can be accessed via the /describe/statement/schema path of the API."
        # type: object
        type: string
    example:
      - id: Pez1_809_1
        text: "Andreas Reuter (ca. 1648 Kremsmünster – 1715 Gleink) war Konventuale von Gleink. Er war Doktor der Theologie, apostolischer Protonotar und wirkte in Gleink als Ökonom sowie insgesamt 22 Jahre lang als Prior. Als solcher begegnet er 1708 als Unterzeichner der Rotel auf Abt Rupert von Kimpflern und 1710 in seinem Brief an Bernhard Pez."
      - graph:
          - "@context" : "http://pez-digital.at/prosopography-schema.json-ld"
            "@graph": 
            - "@id" : "http://pez-digital.at/Lindner-Album_Ettalense253f"
              "assignedTo" : 
              - "@id" : "http://pez-digital.at/placidus_Seiz"
              "hasName" :  
              - "@value" : "Placidus Seitz"
  Source:

    properties:
      id:
        $ref: "#/definitions/id"
      uri:
        $ref: "#/definitions/uri"
      sameAs:
        $ref: "#/definitions/sameAs"
      metadata:
        description: a verbal or formal bibliographical/archival description of the source
        type: string
        # Allow string or structured metadata
    example:
      - id: PezNachlassVol1
        sameAs: https://e-book.fwf.ac.at/o:370
        metadata: "Die gelehrte Korrespondenz der Brüder Pez, Text, Regesten, Kommentare; Band 1: 1709–1715, bearb. v. Thomas Wallnig u. Thomas Stockinger, Wien u. Köln: Böhlau, 2010"
      - id: "Pez#474"
        metadata: "Melk, Stiftsarchiv, Kt. 07 Patres 07, II, 673r-675v"
      - id: "Lindner-Album_Ettalense253f."
        metadata: "Lindner: Album Ettalense, S. 253f."
  id:
    description: the local id of the object (factoid, person, source, statement)
    type: string
  uri:
    description: the uri of the object (factoid, person, source, statement)
    type: string
    #ToDo: uri as type e.g. by pattern?
  sameAs:
    description: the uri of an object (factoid, person, source, statement) referenced with owl:sameAs
    type: string
  Error:
    properties:
      code:
        type: string
      message:
        type: string
responses:
  BadRequestError:
    description: Bad request. Caused by unknown parameters or illegal parameter values
    schema:
      $ref: "#/definitions/Error"
  Standard500ErrorResponse:
    description: An unexpected error occurred. #I'm not sure if we need this in the API as a 500 could occur anytime and for many reasons and should normaly not expose the reason to the public. The typical message would be something like the standard "Internal Server Error".
    schema:
      $ref: "#/definitions/Error"
  NotImplementedError:
    description: 
      Functionality not implemented. Some implementations will only support read operations. 
      For any data modifying request they must return a 501 response.
    schema:
      $ref: "#/definitions/Error"
parameters:
  size:
    name: size
    in: query
    description: sets the  number of objects returned per page. Should the API define a default value?
    type: integer
  page:
    name: page
    in: query
    description: 
      Sets the page number of returned objects. 
      So if size is set to 10 and page is set to 2, the objects 11-20 will be returned.
      Default value is 1.
    type: integer
  id:
    name: id
    in: path
    required: true
    type: string
    description: can be either the local id, or the uri or the uri of a owl:sameAs entry
  sort_by:
    name: sort_by
    type: string
    in: query
    description: defines the sort order of the returned factoids. TODO does this make sense? TODO What is the default sort order? TODO Allowed values should be discussed TODO Do we need an additional order parameter? (asc, desc)?
  p_id:
    name: p_id
    type: string
    in: query
    description: filter by person id
  p:
    name: p
    type: string
    in: query
    description: filter by applying a pattern on persons (fulltext search)
  st_id:
    name: st_id
    type: string
    in: query
    description: filter by statement id
  st:
    name: st
    type: string
    in: query
    description: filter by applying a pattern on statements (fulltext search)
  s_id:
    name: s_id
    type: string
    in: query
    description: filter by source id
  s:
    name: s
    type: string
    in: query
    description: filter by applying a pattern on sources (fulltext search)
  f:
    name: f
    type: string
    in: query
    description: filter by applying a pattern on factoid (fulltext search)
  f_id:
    name: f_id
    type: string
    in: query
    description: filter by factoid id