swagger.yaml

---
swagger: '2.0'
info:
  version: 1.0.0
  title: API for Astrophysics Data System (ADS)
  description: |
    ## API for the ADS project.

    The source code for individual components can be found at:

      - search: https://github.com/adsabs/solr-service
      - server side store: https://github.com/adsabs/myads
      - orcid: https://github.com/adsabs/orcid-service

host: api.adsabs.harvard.edu
basePath: /v1
externalDocs:
  description: Complete documentation describing how to use this API
  url: https://github.com/adsabs/adsabs-dev-api
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  ApiKeySecurity:
    type: apiKey
    in: header
    name: Authorization
  OauthSecurity:
    type: oauth2
    flow: accessCode
    authorizationUrl: 'https://api.adsabs.harvard.edu/oauth/authorization'
    tokenUrl: 'https://api.adsabs.harvard.edu/oauth/token'
    scopes:
      user: User scopes
      api: Api user scopes
      'store-query': Save into RDB
      'execute-query': Run saved query
      'store-preferences': Acces or save user preferences
      'ads-consumer:orcid': Access to the privileged operations

security:
  - OauthSecurity: []
paths:
  '/search/query':
    get:
      description: |

        Query the search engine and return results. All parameters have to be properly url-encoded UTF-8. The response body will always be json encoded.

        ## Example result
        ```JSON
        {
            "bibcode": "2012A&A...542A..16R",
            "author": [
              "Ranalli, P.",
              "Comastri, A.",
              ...
            ],
            "pub": "Astronomy and Astrophysics",
            "identifier": [
              "2012arXiv1204.4485R",
              "arXiv:1204.4485",
              "2012A&A...542A..16R"
            ],
            "title": "X-ray properties of radio-selected star forming galaxies in the Chandra-COSMOS survey",
            "property": [
              "REFEREED",
              "ARTICLE"
            ],
            "abstract": "X-ray surveys contain sizable numbers of star forming galaxies, ...",
            "keyword": [
              "astronomy x rays",
              "astronomy radio",
              "galaxies fundamental parameters",
              "galaxies star clusters",
              "galaxies active"
            ],
            "aff": [
              "Università di Bologna, Dipartimento di Astronomia, via Ranzani 1, 40127, Bologna, Italy ; Institute of Astronomy and Astrophysics, National Observatory of Athens, Palaia Penteli, 15236, Athens, Greece; INAF - Osservatorio Astronomico di Bologna, via Ranzani 1, 40127, Bologna, Italy",
              "INAF - Osservatorio Astronomico di Bologna, via Ranzani 1, 40127, Bologna, Italy",
            ],
          }
        ```
        ### Example Search Requests


        Query | Explanation
        ------|-------------------------------------------------
         `q=bibcode:2011ApJ...737..103S` |  Search by bibcode
         `q=black+holes&fq=database:astronomy` |  Search for "black holes", restricted to astronomy content
         `q=dark+energy&fq=author:"Civano,+F"&sort=citation_count+desc` |  Search for "dark energy", filter by author, sort by citation count
        `q=dark+energy&sort=citation_count+desc&fl=bibcode,property` |   Return *bibcode* and *property* values
        `q=author:"Kurtz,+M"&fq=property:refereed`|   Limit a search to only refereed articles
        `q=transiting+exoplanets&rows=200`|  Search for "transiting exoplanets", get 200 rows
        `q=transiting+exoplanets&rows=200&start=201`|   Same search but get the next 200 rows

      security:
        - OauthSecurity: []
      parameters:
        - $ref: "#/parameters/q"
        - $ref: "#/parameters/fq"
        - $ref: "#/parameters/fl"
        - $ref: "#/parameters/start"
        - $ref: "#/parameters/rows"
        - $ref: "#/parameters/sort"
      responses:
        200:
          $ref: "#/responses/SearchResults"
        404:
          $ref: "#/responses/SearchResults"
        499:
          description: Server too busy
        500:
          description: Server error
      tags:
        - search

  '/search/qtree':
    get:
      description: |
        Returns a `query tree` (Abstract Syntax Tree - AST) as understood by our query parser. The structure can be used by external applications to rewrite the query or check its syntactic correctnes.

        ## Example result
        ```JSON
        {
             "qtree": "\n{\"name\":\"OPERATOR\", \"label\":\"DEFOP\", \"children\": [\n    {\"name\":\"MODIFIER\", \"label\":\"MODIFIER\", \"children\": [\n        {\"name\":\"TMODIFIER\", \"label\":\"TMODIFIER\", \"children\": [\n            {\"name\":\"FIELD\", \"label\":\"FIELD\", \"children\": [\n                {\"name\":\"QNORMAL\", \"label\":\"QNORMAL\", \"children\": [\n                    {\"name\":\"TERM_NORMAL\", \"input\":\"star\", \"start\":0, \"end\":3}]\n                }]\n            }]\n        }]\n    }]\n}",
             "responseHeader": {
              "status": 0,
              "QTime": 6,
              "params": {
               "q": "star",
               "wt": "json",
               "fl": "id"
              }
             }
            }
        ```
      security:
        - OauthSecurity: []
      parameters:
        - $ref: "#/parameters/q"
      responses:
        200:
          $ref: "#/responses/QTree"
  '/search/bigquery':
    post:
      description: |
        Search endpoint which accepts list of many IDs (bibcodes). Supports paging.

        Returns standard search results, but accepts as input very large query (i.e. a query that can be expressed only as a list of search
        criteria, typically IDs). There is currently no limit to the size of the submitted data (besides buffer/time limits imposed by our API
        frontend), however there are severe limits on how often you can call this enpoint. Typically, only 100 requests per day are allowed.

        The `bigquery` is always executed as a filter **after** the main query (to filter out unwanted results and keep only the results
        specified by the `bigquery`). You may want to use `q=*:*` to filter contents of the whole database, however it is advisable to make
        the `q` as specific as possible. Broad queries have higher `qTime` (execution time) and that will be counted towards your rate-limit
        (in the future).


        The bigquery filter is *applied only after* the main search (ie: it limits results of the main search).

        ## Example request

        ```python
          import requests
          bibcodes="bibcode\n1907AN....174...59.\n1908PA.....16..445.\n1989LNP...334..242S"
          r = requests.post('https://api.adsabs.harvard.edu/v1/search/bigquery',
               params={'q':'*:*', 'wt':'json', 'fq':'{!bitset}', 'fl':'bibcode'},
               headers={'Authorization': 'Bearer:TOKEN'},
               data=bibcodes)
        ```
      security:
        - OauthSecurity:
          - api
      parameters:
        - $ref: "#/parameters/q"
        - name: filestream
          in: formData
          required: true
          type: string
          description:  |
            Newline separated list of values, the first line specifies the index field, the rest are the search values. <br/> Currently, we
            allow to search in `bibcode` index only. You can submit `canonical` as well as `alternate` bibcodes - the search will automatically
            match both. In the future, the list of available indexes may be extended).
        - name: 'Content-Type'
          in: header
          required: false
          description: |
            Default is `big-query/csv`, it influences the way how the values from the `filestream` parameter are parsed. In the future ADS may support `json` and some other formats. The header can also be used to pass additional information to the query parser.
          default: big-query/csv
          type: string
        - $ref: "#/parameters/fq"
        - $ref: "#/parameters/fl"
        - $ref: "#/parameters/start"
        - $ref: "#/parameters/rows"
        - $ref: "#/parameters/sort"
      responses:
        200:
          $ref: "#/responses/SearchResults"
        404:
          $ref: "#/responses/SearchResults"
        499:
          description: Server too busy
        500:
          description: Server error
      tags:
        - search

  '/vault/query':
    post:
      description: |
        Save a query for later execution.

        ## Example request

        ```bash
          $ curl 'https://api.adsabs.harvard.edu/v1/vault/query' -H 'Authorization: Bearer:TOKEN' \
            -X POST -d $'{"q":"*:*, "bigquery": "bibcode\\n15IAUGA..2257982A\\n2015IAUGA..2257768A\\n2015IAUGA..2257639R\\n2015ASPC..492..208G\\n2015ASPC..492..204F\\n2015ASPC..492..189A\\n2015ASPC..492..150T\\n2015ASPC..492...85E\\n2015ASPC..492...80H\\n2015AAS...22533656H"}' \
            -H 'Content-Type: application/json'

          > {"qid": "dcd173130bbbbb957eafd866baf38b2c", "numFound": 9}
        ```
      parameters:
        - name: jsonobj
          description: JSON object holding the values to submit.
          required: true
          in: body
          schema:
            $ref: "#/definitions/vaultObject"
      tags:
        - search
      security:
        - OauthSecurity:
          - store-query
      responses:
        200:
          $ref: "#/responses/VaultResponse"
        404:
          description: QID object not found
  '/vault/query/{queryId}':
    get:
      description: |
        Retrive information about the previously stored query.

        ## Example output

        ```JSON
        {
            "numfound": 9,
            "qid": "dcd173130bbbbb957eafd866baf38b2c",
            "query": "{\"query\": \"fq=%7B%21bitset%7D&q=%2A%3A%2A\", \"bigquery\": \"bibcode\\n15ASPC..495..40015IAUGA..2257982A\\n2015IAUGA..2257768A\\n2015IAUGA..2257639R\\n2015ASPC..492..208G\\n2015ASPC..492..204F\\n2015ASPC..492..189A\\n2015ASPC..492..150T\\n2015ASPC..492...85E\\n2015ASPC..492...80H\\n2015AAS...22533656H\"}"
        }
        ```
      parameters:
        - name: queryId
          description: QID returned from the POST operation
          required: true
          in: path
          type: string
      tags:
        - search
      security:
        - OauthSecurity:
          - store-query
      responses:
        200:
          $ref: "#/responses/VaultResponse"
        404:
          description: QID object not found

  '/vault/execute_query/{queryId}':
    get:
      description: |
        Search using the stored query and return the same data as Search API endpoint.

        ## Example response

        ```JSON
          {
            "response": {
                "docs": [
                    {
                        "id": "10690723"
                    },
                    {
                        "id": "11057363"
                    },
                    {
                        "id": "10564749"
                    },
                    {
                        "id": "10796089"
                    },
                    {
                        "id": "10867252"
                    },
                    {
                        "id": "10867221"
                    },
                    {
                        "id": "10867251"
                    },
                    {
                        "id": "10867277"
                    },
                    {
                        "id": "11057812"
                    }
                ],
                "numFound": 9,
                "start": 0
            },
            "responseHeader": {
                "QTime": 6,
                "params": {
                    "fl": "id",
                    "fq": "{!bitset}",
                    "q": "*:*",
                    "wt": "json"
                },
                "status": 0
            }
          }
        ```
      parameters:
        - name: queryId
          description: QID returned from the POST operation
          required: true
          in: path
          type: string
        - name: jsonobj
          description: You can submit query parameters that override parts of the saved query.
          required: false
          in: body
          schema:
            $ref: "#/definitions/vaultObject"
      tags:
        - search
      security:
        - OauthSecurity:
          - execute-query
      responses:
        200:
          $ref: "#/responses/SearchResults"
        404:
          description: QID object not found

  '/vault/user-data':
    get:
      description: |
        Retrive stored preferences. No parameter is passed besides the `Authorization` header; user
        is identified based on that.
      responses:
        200:
          description: JSON
        404:
          description: User not found
      security:
        - OauthSecurity:
          - store-preferences
      x-ratelimit:
        period: day
        limit: 1000
      tags:
        - user
        - store
    post:
      description: |
        Endpoint for saving user preferences. Used mostly by BumbleBee client.

        ## Example request

        ```bash
          $ curl -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>" "https://api.adsabs.harvard.edu/v1/vault/user-data" -X POST -d $'{"foo": "bar"}'
          > {"foo": "bar"}
        ```
      parameters:
        - $ref: "#/parameters/jsonpayload"
      responses:
        200:
          description: JSON
        404:
          description: User not found
      security:
        - OauthSecurity:
          - store-preferences
      x-ratelimit:
        period: day
        limit: 100
      tags:
        - user
        - store


  '/vault/configuration/{key}':
    get:
      description: |
        Retrive various configuration options for the Bumblebee client. This config is static and controlled by ADS;
        there is no way to update it from outside.

        ## Example Response

        ```JSON
        {
            "link_servers": [
                {
                    "gif": "http://sfx.brown.edu:8888/sfx_local/sfx.gif",
                    "link": "http://sfx.brown.edu:8888/sfx_local",
                    "name": "Brown University Library"
                },
                {
                    "gif": "http://sfx.caltech.edu:8088/images/sfx.gif",
                    "link": "http://sfx.caltech.edu:8088/caltech",
                    "name": "California Institute of Technology"
                },
                {
                    "gif": "http://elibrary.cf.ac.uk/sfx/img/azlist_ver3/cardiffsfx.gif",
                    "link": "http://elibrary.cf.ac.uk/sfx",
                    "name": "Cardiff University"
                }]
        }
        ```
      parameters:
        - name: key
          in: path
          description: Optional. Denotes the key that should be returned from the configuration. When empty, default is to return everything.
          type: string
          required: true
      responses:
        200:
          description: JSON
        404:
          description: Key not found
      security:
        - OauthSecurity: []
      x-ratelimit:
        period: day
        limit: 100
      tags:
        - user


  '/orcid/get-profile/{orcidId}':
    get:
      description: |
        Check with ORCiD and downloads the fresh profile from the ORCiD API. We can return the orcid profile only if a user ever logged in with
        ADS (and also the OAuth access_token is stil valid).

        ## Example Response

        ```JSON
          {
          "error-desc": null,
          "message-version": "1.2",
          "orcid-profile": {
              "client-type": null,
              "group-type": null,
              "orcid": null,
              "orcid-activities": {
                  "affiliations": null,
                  "funding-list": null,
                  "orcid-works": {
                      "orcid-work": [
                          {
                              "country": null,
                              "created-date": {
                                  "value": 1446830582917
                              },
                              "journal-title": null,
                              "language-code": null,
                              "last-modified-date": {
                                  "value": 1446830582917
                              },
                              "publication-date": {
                                  "day": null,
                                  "media-type": null,
                                  "month": {
                                      "value": "08"
                                  },
                                  "year": {
                                      "value": "2015"
                                  }
                              },
                              "put-code": "20054210",
                              "short-description": "Whether or not scholarly publications are going through an evolution or revolution, one comforting certainty remains: the NASA Astrophysics Data System (ADS) is here to help the working astronomer and librarian navigate through the increasingly complex communication environment we find ourselves in. Born as a bibliographic database, today's ADS is best described as a an \"aggregator\" of scholarly resources relevant to the needs of researchers in astronomy and physics. In addition to indexing content from a variety of publishers, data and software archives, the ADS enriches its records by text-mining and indexing the full-text articles, enriching its metadata through the extraction of citations and acknowledgments and the ingest of bibliographies and data links maintained by astronomy institutions and data archives. In addition, ADS generates and maintains citation and co-readership networks to support discovery and bibliometric analysis.In this talk I will summarize new and ongoing curation activities and technology developments of the ADS in the face of the ever-changing world of scholarly publishing and the trends in information-sharing behavior of astronomers. Recent curation efforts include the indexing of non-standard scholarly content (such as software packages, IVOA documents and standards, and NASA award proposals); the indexing of additional content (full-text of articles, acknowledgments, affiliations, ORCID ids); and enhanced support for bibliographic groups and data links. Recent technology developments include a new Application Programming Interface which provides access to a variety of ADS microservices, a new user interface featuring a variety of visualizations and bibliometric analysis, and integration with ORCID services to support paper claiming.",
                              "source": {
                                  "source-client-id": {
                                      "host": "orcid.org",
                                      "path": "APP-BA5POB6F5D7CTHX2",
                                      "uri": "http://orcid.org/client/APP-BA5POB6F5D7CTHX2",
                                      "value": null
                                  },
                                  "source-date": {
                                      "value": 1446830582917
                                  },
                                  "source-name": {
                                      "value": "NASA ADS"
                                  },
                                  "source-orcid": null
                              },
            # output truncated ....
        ```

      parameters:
        - $ref: "#/parameters/orcidId"
      responses:
        200:
          description: JSON
        404:
          description: |
            JSON

            When the user revoked their OAuth ORCiD token

            ```JSON
            {
             "error" : "We do not have access_token for: 0000-0000-0000-0000"
            }
            ```

            If the ORCiD ID is not known to us

            ```JSON
            {
             "error" : "We do not have a record for: 0000-0000-0000-0000"
            }
            ```

      security:
        - OauthSecurity:
          - ads-consumer:orcid
      x-ratelimit:
        period: day
        limit: 100
      tags:
        - user
        - orcid


  '/orcid/export/{iso_date}':
    get:
      description: |
        Return information about users who recently updated their ORCiD information through Bumblebee (ADS UI). This includes also
        users who just accessed their ORCiD profiles, even if they didn't make new claims. This enpoint always returns maximum of 10
        records created since (inclusive) the requested date. To access the next records, use the `updated` date + 1 additional microsecond.


        ## Example Response

        ```JSON
        [
            {
                "created": "2015-11-15T17:46:28.657982",
                "orcid_id": "0000-0002-9384-846X",
                "updated": "2015-11-15T20:58:27.656195",
                "info": {},
                "profile": {
                    "error-desc": null,
                    "message-version": "1.2",
                    "orcid-profile": {
                        "client-type": null,
                        "group-type": null,
                        "orcid": null,
                        "orcid-activities": {
                            "affiliations": {
                                "affiliation": [
                                    {
                                        "created-date": {
                                            "value": 1438088550409
                                        },
                                        "department-name": null,
                                        "end-date": null,
                                        "last-modified-date": {
                                            "value": 1438088550409
                                        },
                                        "organization": {
                                            "address": {
                                                "city": "Firenze",
                                                "country": "IT",
                                                "region": "Toscana"
                                            },
                                            "disambiguated-organization": {
                                                "disambiguated-organization-identifier": "56860",
                                                "disambiguation-source": "RINGGOLD"
                                            },
                                            "name": "Osservatorio Astrofisico di Arcetri"
                                        },
                                        "put-code": "1060794",
                                        "role-title": "Researcher",
                                        "source": {
                                            "source-client-id": null,
                                            "source-date": {
                                                "value": 1438088550409
                                            },
                                            "source-name": {
                                                "value": "Simone Bianchi"
                                            },
                                            "source-orcid": {
                                                "host": "orcid.org",
                                                "path": "0000-0002-9384-846X",
                                                "uri": "http://orcid.org/0000-0002-9384-846X",
                                                "value": null
                                            }
                                        },
                           # output truncated
            },
            {
             ...
            }
        ]
        ```

      parameters:
        - name: iso_date
          in: path
          description: |
            Date in ISO format (RFC3339, UTC time zone, ie. '2008-09-03T20:56:35.450686Z')
          type: string
          required: true
        - name: fields
          in: query
          description: 'List of fields to return in response, allowed values are: `orcid_id`, `created`, `updated`, `profile`, `info`'
          type: array
          uniqueItems: true
          collectionFormat: csv
          items:
            type: string
            enum:
              - orcid_id
              - created
              - updated
              - profile
              - info

      responses:
        200:
          description: JSON
      security:
        - OauthSecurity:
          - ads-consumer:orcid
      x-ratelimit:
        period: day
        limit: 1000
      tags:
        - orcid


  '/orcid/preferences/{orcidId}':
    get:
      description: |
        Clients can store various data about the user (ie: Bumblebee saves here alternative names
        and user preferences associated to the ORCiD display).


        ## Example Response

        ```json
        {
          "alternativeNames" : ["Doe, J", "Doe X, J"]
        }
        ```

      parameters:
        - $ref: "#/parameters/orcidId"
        - $ref: "#/parameters/OrcidAuthorization"
      responses:
        200:
          description: JSON
      security:
        - OauthSecurity: []
      x-ratelimit:
        period: day
        limit: 1000
      tags:
        - orcid
    post:
      description: |
        Post a JSON payload to **replace** the existing stored values.

        ## Example Request

        ```command-line

        $ curl 'https://api.adsabs.harvard.edu/v1/preferences/0000-00002-9384-846X' -H 'Authorization: Bearer:TOKEN' -H 'Orcid-Authorization: Bearer:ea12a66a-2a07-49fc-b0cb-9d0967c484c8' -X POST -d $'{"foo":"bar"}' -H 'Content-Type: application/json'

        > {"foo": "bar"}
        ```

        ## Example Response

        ```json
        {
          "alternativeNames" : ["Doe, J", "Doe X, J"]
        }
        ```

      parameters:
        - $ref: "#/parameters/orcidId"
        - $ref: "#/parameters/OrcidAuthorization"
        - $ref: "#/parameters/jsonpayload"
      responses:
        200:
          description: JSON
      security:
        - OauthSecurity: []
      x-ratelimit:
        period: day
        limit: 1000
      tags:
        - orcid


definitions:
  qtree:
    type: object
    properties:
      responseHeader:
        $ref: "#/definitions/responseHeader"
      qtree:
        type: string
        description: "serialized JSON"
  results:
    type: object
    properties:
      responseHeader:
        $ref: "#/definitions/responseHeader"
      docs:
        type: array
        items:
          $ref: "#/definitions/doc"
  doc:
    type: object
    required:
      - id
    properties:
      id:
        type: string
      bibcode:
        type: string
      title:
        type: string
  responseHeader:
    type: object
    properties:
      status:
        description: Status code as returned by the search engine
        type: integer
      QTime:
        type: integer
        description: search time in millisecs (only search, without faceting, latency and all other steps)
  vaultObject:
    type: object
    properties:
      numfound:
        readOnly: true
        type: integer
        description: |
          Number of docs this query found (the last time it was executed; this number is up to
          date only when the query is stored). But if you see number higher than 0 then you can be sure that
          the query was executed.

      qid:
        readOnly: true
        type: string
        description: |
          Query ID (unique hash identifying all the parameters; it is computed from the supplied query
          parameters)

      query:
        type: string
        description: JSON serialized query parameters
      bigquery:
        type: string
        description: |
          new line separated list of bibcodes, the first line is the name of the index that will be
          searched, right now we only support search in `bibcode` index

responses:
  QTree:
    description: Abstract Syntax Tree of a Parsed query
    schema:
      $ref: "#/definitions/qtree"
  SearchResults:
    description: Results returned by the search engine
    schema:
      $ref: "#/definitions/results"

  VaultResponse:
    description: Response from myads service
    schema:
      $ref: "#/definitions/vaultObject"





parameters:
  q:
    name: q
    description: Query string; for detailed documentation go to http://ui.adsabs.harvard.edu/help
    in: query
    required: true
    type: string
  rows:
    name: rows
    description: How many records to return for this request (default=10, maximum=200)
    in: query
    required: false
    type: integer
    default: 10
    maximum: 200
  fq:
    name: fq
    description: Additional filters applied on top of the results of the main query.
    in: query
    required: false
    type: array
    maxItems: 10
    collectionFormat: multi
    items:
      type: string
  fl:
    name: fl
    description: Comma delimited set of fields to return; default is 'id'
    in: query
    default:
      - id
    type: array
    uniqueItems: true
    collectionFormat: csv
    items:
      type: string
      enum:
        - abstract
        - ack
        - aff
        - alternate_bibcode
        - alternate_title
        - arxiv_class
        - author
        - bibcode
        - bibgroup
        - bibstem
        - body
        - citation_count
        - copyright
        - data
        - database
        - doi
        - doctype
        - first_author
        - grant
        - id
        - identifier
        - indexstamp
        - issue
        - keyword
        - lang
        - orcid_pub
        - orcid_use
        - orcid_other
        - page
        - property
        - pub
        - pubdate
        - read_count
        - title
        - vizier
        - volume
        - year
  start:
    name: start
    description: For pagination, offset of the first returned result (default=0)
    in: query
    required: false
    type: integer
    default: 0
  sort:
    name: sort
    description: |
      The format is 'field direction' where direction is one of 'asc' or 'desc' and field is any of the valid indexes. The default sorting is by relevance (computed by our search engine). Example\: 'sort=read_count+desc' Some useful fields to sort by may be pubdate, citation_count, or num_readers.
    in: query
    required: false
    type: string
  orcidId:
    name: orcidId
    in: path
    description: ORCiD ID, i.e. '0000-0000-00000-00000'
    type: string
    required: true
  OrcidAuthorization:
    name: 'Orcid-Authorization'
    in: header
    description: '`access_token` of the orcid user (will be passed on to the ORCiD API)'
    type: string
  jsonpayload:
    name: jsonpayload
    in: body
    description: |
      JSON object, to be stored for the user. **WARNING**: the JSON will replace the existing one.
      If you send an empty POST request, the stored data will be replaced with `{}`.
    schema:
      type: object