API_documentation_Python/Libraries_API_Python.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Libraries\n",
    "This notebook explains how to retrieve data for and edit private and public ADS libraries. Examples here will be shown using Python with the use of the [requests](http://docs.python-requests.org/en/master/) library, though the same work could be done using the [unofficial Python ADS library](https://ads.readthedocs.io/en/latest/) or curl commands on the command line (see the \"API documentation - UNIX shell\" folder in this same repository).\n",
    "\n",
    "The base URL for library queries is\n",
    "```\n",
    "https://api.adsabs.harvard.edu/v1/biblib/<endpoint>\n",
    "```\n",
    "where the allowed `<endpoint>` values are:\n",
    "* `/libraries`: create or view all libraries for a given user; GET or POST methods allowed\n",
    "* `/libraries/<library_id>`: view a specific library; GET method is allowed\n",
    "* `/documents/<library_id>`: add and remove records from a specific library, update the metadata for a specific library, or delete an entire library; POST, PUT, and DELETE methods are allowed\n",
    "* `/query/<library_id>`: add and remove records from a specific library based on the results of a given search query; POST and GET methods are allowed\n",
    "* `/permissions/<library_id>`: view or modify the permissions for a specific library; GET and POST methods are allowed\n",
    "* `/transfer/<library_id>`: transfer ownership of a library to another ADS user; GET and POST methods are allowed\n",
    "\n",
    "These endpoints are discussed further below, with examples.\n",
    "\n",
    "In all examples below, `token` should be replaced with [your own API token](https://ui.adsabs.harvard.edu/user/settings/token). If you haven't worked with our API before, it's recommended that you read the [README](https://github.com/adsabs/adsabs-dev-api/blob/master/README.md) before beginning."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# import the requests package and set your token in a variable for later use\n",
    "import requests\n",
    "\n",
    "token=\"your-token-here\""
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Permissions\n",
    "  * **owner**: Owns the library. Can read libraries, add/remove bibcodes, delete the library, add/remove permissions, transfer ownership of the library.\n",
    "  * **admin**: Can read libraries, add/remove bibcodes, add/remove permissions.\n",
    "  * **write**: Can read libraries, add/remove bibcdes.\n",
    "  * **read**: Can read libraries.\n",
    "\n",
    "Any other user that does not have a permission to the library they try to visit, can only see it if it is public. If the user has no permissions, they cannot view this library."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `/libraries`\n",
    "Create a library or view all libraries for a given user, depending on the method used.\n",
    "\n",
    "#### GET method\n",
    "View all libraries for the user associated with the given API token.\n",
    "\n",
    "The number of libraries can be controlled by specifiying the `start` and `rows` params.\n",
    "\n",
    "The sort order of the returned libraries can be specified with `sort` and `order`.\n",
    "\n",
    "The libraries can be sorted on either `date_created`, or `date_last_modified` and the `order` can be either `asc` or `desc`. The default behavior is `sort=date_created` and `order=asc`\n",
    "\n",
    "*Return data*:\n",
    "  * name: (string) name of the library\n",
    "  * id: (string) ID of the library\n",
    "  * description: (string) description of the library\n",
    "  * num_documents: (integer) number of documents in the library\n",
    "  * date_created: (string) ISO date library was created\n",
    "  * date_last_modified: (string) ISO date library was last modified\n",
    "  * permission: (string) permission type, can be: 'read', 'write', 'admin', or 'owner'\n",
    "  * public: (boolean) true means it is a public library\n",
    "  * num_users: (integer) number of users with permissions to this library\n",
    "  * owner: (string) ID of the user who created the library"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "11"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "results = requests.get(\"https://api.adsabs.harvard.edu/v1/biblib/libraries\",\n",
    "                       headers={'Authorization': 'Bearer ' + token})\n",
    "len(results.json()['libraries'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "11"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "results = requests.get(\"https://api.adsabs.harvard.edu/v1/biblib/libraries/?start=0&rows=11&sort=date_created&order=asc\",\n",
    "                       headers={'Authorization': 'Bearer ' + token})\n",
    "len(results.json()['libraries'])"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### POST method\n",
    "Create a library for the requesting user. Returns the metadata of the library created.\n",
    "\n",
    "In addition to the usual token header and request URL, you must specify that this is a POST request. The POST payload must also be passed using the `data` keyword and should be in JSON format. We use the `json` library here to convert between Python dictionaries and JSON strings. The payload should include the following keys:\n",
    "  * name: (string) optional; name of the library (must be unique for that user). The default is `Untitled Library`, with an incremented integer starting with 1 appended\n",
    "  * description: (string) optional; description of the library. The default is \"My ADS library\"\n",
    "  * public: (boolean) optional; set to true to allow public access. Note: the Boolean value is case senstitive, and must be entered in lowercase. The default is false, or a private library\n",
    "  * bibcode: (list) optional; list of bibcodes to add. The default is an empty library\n",
    "\n",
    "The metadata of the library you just created will be returned after the request:\n",
    "  * name: (string) name of the library\n",
    "  * id: (string) ID of the library\n",
    "  * description: (string) description of the library"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'name': 'API Library',\n",
       " 'id': 'Z7cCXDXQRC2HxB8CA8uu2g',\n",
       " 'description': 'This library is created via API',\n",
       " 'bibcode': ['1975CMaPh..43..199H', '1973PhRvD...7.2333B']}"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import json\n",
    "\n",
    "payload = {\"name\": \"API Library\", \n",
    "           \"description\": \"This library is created via API\", \n",
    "           \"public\": True, \n",
    "           \"bibcode\": [\"1975CMaPh..43..199H\", \"1973PhRvD...7.2333B\"]}\n",
    "results = requests.post(\"https://api.adsabs.harvard.edu/v1/biblib/libraries\",\n",
    "                        headers={'Authorization': 'Bearer ' + token}, \n",
    "                        data=json.dumps(payload))\n",
    "results.json()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### /libraries/&lt;library_id&gt;\n",
    "View a specific library. The `library_id` (string) is the unique identifier of the library, given via the `/libraries` GET method detailed above.\n",
    "\n",
    "To edit or delete a library, see the `/document/<library_id>` endpoint section below.\n",
    "\n",
    "#### GET\n",
    "Obtains all the documents in a given library. \n",
    "\n",
    "*Return data*:\n",
    "  * documents: (list) a list containing the bibcodes in the library\n",
    "  * solr: (dict) the response from the solr bigquery endpoint\n",
    "  * metadata: (dict) Contains the following:\n",
    "        * name: (string) name of the library\n",
    "        * id: (string) ID of the library\n",
    "        * description: (string) description of the library\n",
    "        * num_documents: (integer) number of documents in the library\n",
    "        * date_created: (string) ISO date library was created\n",
    "        * date_last_modified: (string) ISO date library was last modified\n",
    "        * permission: (sting) Permission type, can be 'read', 'write', 'admin', or 'owner'\n",
    "        * public: (boolean) true means it is public\n",
    "        * num_users: (integer) number of users with permissions to this library\n",
    "        * owner: (string) identifier of the user who created the library\n",
    "  * updates: (dict) Contains the following\n",
    "        * num_updated: (integer) number of documents modified based on the response from solr\n",
    "        * duplicates_removed: (integer) number of files removed because they are duplications\n",
    "        * update_list: (list, dict) list of dictionaries such that a single element described the original bibcode (key) and the updated bibcode now being stored (item)\n",
    "\n",
    "The following type of user can read a library:\n",
    "  - owner\n",
    "  - admin\n",
    "  - write\n",
    "  - read"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'documents': ['1975CMaPh..43..199H', '1973PhRvD...7.2333B'],\n",
       " 'solr': {'responseHeader': {'status': 0,\n",
       "   'QTime': 34,\n",
       "   'params': {'q': '*:*',\n",
       "    'fl': 'bibcode,alternate_bibcode',\n",
       "    'start': '0',\n",
       "    'internal_logging_params': 'X-Amzn-Trace-Id=Root=1-64011d99-0652bc5e7903b9374dff1eee',\n",
       "    'fq': '{!bitset}',\n",
       "    'sort': 'date desc',\n",
       "    'rows': '20',\n",
       "    'wt': 'json'}},\n",
       "  'response': {'numFound': 2,\n",
       "   'start': 0,\n",
       "   'docs': [{'bibcode': '1975CMaPh..43..199H'},\n",
       "    {'bibcode': '1973PhRvD...7.2333B'}]}},\n",
       " 'metadata': {'name': 'API Library',\n",
       "  'id': 'Z7cCXDXQRC2HxB8CA8uu2g',\n",
       "  'description': 'This library is created via API',\n",
       "  'num_documents': 2,\n",
       "  'date_created': '2023-03-02T22:05:01.292494',\n",
       "  'date_last_modified': '2023-03-02T22:05:01.292502',\n",
       "  'permission': 'owner',\n",
       "  'public': True,\n",
       "  'num_users': 1,\n",
       "  'owner': 'kelly.lockhart'},\n",
       " 'updates': {'num_updated': 0, 'duplicates_removed': 0, 'update_list': []}}"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# get the data for the library created above\n",
    "results = requests.get(\"https://api.adsabs.harvard.edu/v1/biblib/libraries/Z7cCXDXQRC2HxB8CA8uu2g\",\n",
    "                       headers={'Authorization': 'Bearer ' + token})\n",
    "results.json()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using the `raw` query parameter allows the user to return the exact bibcodes present in the library, regardless of whether or not they are present in ADS. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'documents': ['1987ApJ...319..136A',\n",
       "  '1988ApJ...324..466W',\n",
       "  '1988ApJ...327..197X',\n",
       "  '1988ApJ...328..699E',\n",
       "  '1988ApJ...329..326C',\n",
       "  '1988ApJ...329..814D',\n",
       "  '1988ApJ...329..820P',\n",
       "  '1988ApJ...329L..25C',\n",
       "  '1988ApJ...330..218W',\n",
       "  '1988ApJ...330L..39E',\n",
       "  '1988ApJ...331..377A',\n",
       "  '1988ApJ...331..388S',\n",
       "  '1988ApJ...332..247B',\n",
       "  '1988ApJ...334..295M',\n",
       "  '1988ApJ...334..308B',\n",
       "  '1988ApJ...334L..81M',\n",
       "  '1988ApJ...334L..87C',\n",
       "  '1988ApJ...335L..53G',\n",
       "  '1988SPIE..922..203C',\n",
       "  '1989ApJ...336..429F'],\n",
       " 'solr': 'Only the raw library was requested.',\n",
       " 'metadata': {'name': 'Test',\n",
       "  'id': 'Os2mtOH-RNiNyBWdSj0m2A',\n",
       "  'description': 'My ADS library',\n",
       "  'num_documents': 534,\n",
       "  'date_created': '2023-02-03T23:49:10.841046',\n",
       "  'date_last_modified': '2023-04-06T17:11:31.095976',\n",
       "  'permission': 'owner',\n",
       "  'public': False,\n",
       "  'num_users': 1,\n",
       "  'owner': 'tjacovich'},\n",
       " 'updates': {}}"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# get the data for the library created above\n",
    "results = requests.get(\"https://api.adsabs.harvard.edu/v1/biblib/libraries/Os2mtOH-RNiNyBWdSj0m2A?raw=true\",\n",
    "                       headers={'Authorization': 'Bearer ' + token})\n",
    "results.json()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### /libraries/operations/&lt;library_id&gt;\n",
    "Perform set operations on one or more libraries. The `library_id` (string) is the unique identifier of the primary library, as specified in the `/libraries` GET response. Depending on the operation, a secondary library ID may need to be passed in the post payload.\n",
    "\n",
    "Function allowed: POST\n",
    "\n",
    "#### POST\n",
    "The following operations are supported:\n",
    "* union: take the union of the primary and the secondary libraries. The result is saved to a new library\n",
    "* intersection: take the intersection of the primary and the secondary libraries. The result is saved to a new library\n",
    "* difference: take the difference between the primary and the secondary libraries. The result is saved to a new library\n",
    "* copy: copy the contents of the primary library into the secondary library. The secondary library is not emptied first; use the empty operation on the secondary library first in order to create a duplicate of the primary library in the secondary library\n",
    "* empty: empty the primary library of its contents (no secondary library ID is needed)\n",
    "\n",
    "Specify that the request is a POST method. You must include a payload, passed via the `data` keyword, in JSON format. The payload must include:\n",
    "* action: (string, required) set operation to perform; allowed values are [`union`, `intersection`, `difference`, `copy`, `empty`]\n",
    "* libraries: (list) list of secondary library IDs; multiple secondary libraries are allowed for [`union`, `intersection`, `difference`]; one secondary library is allowed for `copy`; no secondary libraries are allowed for `empty`\n",
    "* name: (string, optional) name of the new library to be created for [`union`, `intersection`, `difference`]; the name must be unique for a given user; if no name is specified, the name used will be \"Untitled\" with a timestamp\n",
    "* description: (string, optional) description of the new library to be created for [`union`, `intersection`, `difference`]; if no description is specified, the description used will include the set operation used and the primary and secondary library IDs\n",
    "* public: (Boolean, optional) sets whether the new library created by [`union`, `intersection`, `difference`] is publicly viewable or not; the new library will be private unless otherwise specified\n",
    "\n",
    "*Return data*:\n",
    "* name: (string) Name of the library\n",
    "* id: (string) ID of the library\n",
    "* description: (string) Description of the library\n",
    "\n",
    "*Permissions*:\n",
    "The following type of user can perform set operations:\n",
    "* owner\n",
    "* admin\n",
    "* write\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'name': 'New union library',\n",
       " 'id': 'M74cJpN4SXuunD4X7zorpw',\n",
       " 'description': 'Union of libraries Merger Shocks, Metal Grads (IDs: iRZhyhvaSWe0uWwcXKt77w, s56fjycaRMKxw6tDEr31XQ)',\n",
       " 'bibcode': ['2010ApJ...721L..48K',\n",
       "  '2010ASPC..423..355R',\n",
       "  '2011ApJ...734...87R',\n",
       "  '2010ApJ...723.1255R',\n",
       "  '2010ApJ...710L.156R',\n",
       "  '2010ApJ...721..505R']}"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# take the union of 2 libraries, using the default description and public settings\n",
    "payload = {\"action\": \"union\", \n",
    "           \"libraries\": [\"s56fjycaRMKxw6tDEr31XQ\"], \n",
    "           \"name\": \"New union library\"}\n",
    "results = requests.post(\"https://api.adsabs.harvard.edu/v1/biblib/libraries/operations/iRZhyhvaSWe0uWwcXKt77w\", \n",
    "                        headers={'Authorization': 'Bearer ' + token},\n",
    "                        data=json.dumps(payload))\n",
    "results.json()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'name': 'New intersection library',\n",
       " 'id': 'h1j8YE_hTvSVZT7rWhrDXQ',\n",
       " 'description': 'Sample intersection library',\n",
       " 'bibcode': ['1975CMaPh..43..199H']}"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# take the intersection of 2 libraries, using the default public settings\n",
    "payload = {\"action\": \"intersection\", \n",
    "           \"libraries\": [\"YhrBmqfRRd22j-CeBn_1sg\"], \n",
    "           \"name\": \"New intersection library\", \n",
    "           \"description\": \"Sample intersection library\"}\n",
    "results = requests.post(\"https://api.adsabs.harvard.edu/v1/biblib/libraries/operations/Z7cCXDXQRC2HxB8CA8uu2g\", \n",
    "                        headers={'Authorization': 'Bearer ' + token},\n",
    "                        data=json.dumps(payload))\n",
    "results.json()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'name': 'New difference library',\n",
       " 'id': 'A2Mstu9XTy-yzh48oPNrFQ',\n",
       " 'description': 'Sample difference library',\n",
       " 'bibcode': ['2014AJ....147..124M',\n",
       "  '2009ApJ...706..797T',\n",
       "  '2012yCat..21990026H',\n",
       "  '2010AJ....139.2620N',\n",
       "  '2009MNRAS.399..683J',\n",
       "  '2011ASSP...24...11H',\n",
       "  '2010CBET.2338....2N',\n",
       "  '2012yCat.2281....0C',\n",
       "  '2010yCat.7259....0J',\n",
       "  '2009AAS...21360808T',\n",
       "  '2011AJ....142..183N',\n",
       "  '2010A&A...511A..23P',\n",
       "  '2011AAS...21715002C',\n",
       "  '2009ApJ...700..331H',\n",
       "  '2011MNRAS.413.2906D',\n",
       "  '2012ApJS..199...26H',\n",
       "  '2012yCat..51392620N',\n",
       "  '2010noao.prop..445P',\n",
       "  '2010yCat..73990683J',\n",
       "  '2009AJ....138..547S',\n",
       "  '2010AJ....139.1413N',\n",
       "  '2012ApJ...759....6E',\n",
       "  '2020AAS...23528705A',\n",
       "  '2010PASA...27..302M',\n",
       "  '2010AJ....139.1178N',\n",
       "  '2009AJ....138.1667B']}"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# take the difference of 2 libraries\n",
    "payload = {\"action\": \"difference\", \n",
    "           \"libraries\": [\"Z7cCXDXQRC2HxB8CA8uu2g\"], \n",
    "           \"name\": \"New difference library\", \n",
    "           \"description\": \"Sample difference library\", \n",
    "           \"public\": True}\n",
    "results = requests.post(\"https://api.adsabs.harvard.edu/v1/biblib/libraries/operations/YhrBmqfRRd22j-CeBn_1sg\", \n",
    "                        headers={'Authorization': 'Bearer ' + token},\n",
    "                        data=json.dumps(payload))\n",
    "results.json()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'name': 'New intersection library',\n",
       " 'description': 'Sample intersection library',\n",
       " 'public': False,\n",
       " 'bibcode': []}"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# empty a library of all of its bibcode contents\n",
    "payload = {\"action\": \"empty\"}\n",
    "results = requests.post(\"https://api.adsabs.harvard.edu/v1/biblib/libraries/operations/h1j8YE_hTvSVZT7rWhrDXQ\",\n",
    "                        headers={'Authorization': 'Bearer ' + token},\n",
    "                        data=json.dumps(payload))\n",
    "results.json()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'name': 'New intersection library',\n",
       " 'description': 'Sample intersection library',\n",
       " 'public': False,\n",
       " 'bibcode': ['2011ApJ...734...87R', '2010ApJ...721..505R']}"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# copy the bibcode contents from the primary library to the secondary library (this will not empty the library first)\n",
    "payload = {\"action\": \"copy\", \n",
    "           \"libraries\": [\"h1j8YE_hTvSVZT7rWhrDXQ\"]}\n",
    "results = requests.post(\"https://api.adsabs.harvard.edu/v1/biblib/libraries/operations/iRZhyhvaSWe0uWwcXKt77w\",\n",
    "                        headers={'Authorization': 'Bearer ' + token},\n",
    "                        data=json.dumps(payload))\n",
    "results.json()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### /documents/&lt;library_id&gt;\n",
    "Interact with a specific library. The `library_id` (string) is the unique identifier of the library, as specified in the `/libraries` GET response.\n",
    "\n",
    "Functions allowed: add records to a library (POST), delete records from a library (POST), update the metadata of a library (PUT), delete the entire library (DELETE)\n",
    "\n",
    "#### POST\n",
    "Add or delete a document to a given library. Returns the number of documents added or removed\n",
    "\n",
    "Specify that the request is a POST method on the request. You must include a payload, passed via the `data` keyword, in JSON format. The payload must include:\n",
    "  * bibcode: (list) list of bibcodes to be added or removed\n",
    "  * action: (string) 'add' or 'remove' to add or remove the given bibcodes from the specified library\n",
    "\n",
    "*Return data*:\n",
    "  * number_added: (integer) number of documents added (if 'add' is used)\n",
    "  * number_removed: (integer) number of documents removed (if 'remove' is used)\n",
    "  * invalid_bibcodes: (list) List of any specified bibcodes that were not found in ADS\n",
    "\n",
    "*Permissions*:\n",
    "The following type of user can add or remove documents:\n",
    "  * owner\n",
    "  * admin\n",
    "  * write"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'number_added': 1}"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# add a bibcode\n",
    "payload = {\"bibcode\": [\"1974Natur.248...30H\"], \"action\": \"add\"}\n",
    "results = requests.post(\"https://api.adsabs.harvard.edu/v1/biblib/documents/h1j8YE_hTvSVZT7rWhrDXQ\", \n",
    "                        headers={'Authorization': 'Bearer ' + token},\n",
    "                        data=json.dumps(payload))\n",
    "results.json()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'number_removed': 1}"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# remove it again\n",
    "payload = {\"bibcode\": [\"1974Natur.248...30H\"], \"action\": \"remove\"}\n",
    "results = requests.post(\"https://api.adsabs.harvard.edu/v1/biblib/documents/h1j8YE_hTvSVZT7rWhrDXQ\", \n",
    "                        headers={'Authorization': 'Bearer ' + token},\n",
    "                        data=json.dumps(payload))\n",
    "results.json()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### PUT\n",
    "Update the metadata of a given library. Returns updated metadata of the library\n",
    "\n",
    "As with the POST method, you must specify that the request is a PUT method. You must also include a payload, passed via the `data` keyword, in JSON format. The payload can include:\n",
    "\n",
    "*Payload*:\n",
    "  * name: (string) name of the library\n",
    "  * description: (string) description of the library\n",
    "  * public: (boolean) true if the library should be publicly viewable, false if it should be private (note that this is case sensitive and should be lower case)\n",
    "\n",
    "*Note: The above are optional. Leave fields out if they do not need to be updated.*\n",
    "\n",
    "*Return data*:\n",
    "  * name: (string) name of the library\n",
    "  * description: (string) description of the library\n",
    "  * public:(boolean) true if the library is publicly viewable, false if it is private\n",
    "\n",
    "*Note: returns the key/value that was requested to be updated*\n",
    "\n",
    "*Permissions*:\n",
    "The following type of user can update the 'name', 'library', and 'public' attributes:\n",
    "  - owner\n",
    "  - admin"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'name': 'New API library name',\n",
       " 'description': 'New API library description',\n",
       " 'public': False}"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# change the metadata of a library\n",
    "payload = {\"name\": \"New API library name\", \n",
    "           \"description\": \"New API library description\", \n",
    "           \"public\": False}\n",
    "results = requests.put(\"https://api.adsabs.harvard.edu/v1/biblib/documents/h1j8YE_hTvSVZT7rWhrDXQ\",\n",
    "                       headers={'Authorization': 'Bearer ' + token},\n",
    "                       data=json.dumps(payload))\n",
    "results.json()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### DELETE\n",
    "Delete the given library\n",
    "\n",
    "Make sure to specify the DELETE method. No payload is required, as the library ID is passed in the URL. There is no return response to the request.\n",
    "\n",
    "*Permissions*: The following type of user can update a library:\n",
    "  - owner"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'name': 'temp library',\n",
       " 'id': 'LognylxoS5WodJuQaldUQA',\n",
       " 'description': 'My ADS library'}"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# create a temporary library\n",
    "payload = {\"name\":\"temp library\"}\n",
    "results = requests.post(\"https://api.adsabs.harvard.edu/v1/biblib/libraries\",\n",
    "                        headers={'Authorization': 'Bearer ' + token},\n",
    "                        data=json.dumps(payload))\n",
    "results.json()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{}"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# delete the temporary library\n",
    "results = requests.delete(\"https://api.adsabs.harvard.edu/v1/biblib/documents/LognylxoS5WodJuQaldUQA\",\n",
    "                         headers={'Authorization': 'Bearer ' + token})\n",
    "\n",
    "results.json()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### /query/&lt;library_id&gt;\n",
    "Add or remove documents from the library specified by `library_id` (string), where `library_id` is the unique identifier of the library, as specified in the `/libraries` GET response.\n",
    "\n",
    "Functions allowed: add query to a library (POST, GET), delete query from a library (POST).\n",
    "\n",
    "#### POST\n",
    "Add or delete a query to/from a given library. Returns the number of documents added or removed along with the added or removed bibcodes.\n",
    "\n",
    "Specify that the request is a POST method. You must include a payload, passed via the `data` keyword, in JSON format. The payload must include:\n",
    "  * query: (json) dict of query parameters (see Search notebook for more details and example queries.)\n",
    "  * action: (string) 'add' or 'remove' to add or remove the given bibcodes from the specified library\n",
    "\n",
    "*Return data*:\n",
    "  * number_added: (integer) number of documents added (if 'add' is used)\n",
    "  * number_removed: (integer) number of documents removed (if 'remove' is used)\n",
    "  * bibcodes: (list) list of bibcodes added to/removed from the library\n",
    "\n",
    "*Permissions*:\n",
    "The following type of user can add or remove documents:\n",
    "  * owner\n",
    "  * admin\n",
    "  * write\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "# add a query by posting search parameters\n",
    "payload = {\"params\": {\"q\": \"black holes\", \n",
    "                      \"fq\": \"database:astronomy\"}, \n",
    "           \"action\": \"add\"}\n",
    "results = requests.post(\"https://api.adsabs.harvard.edu/v1/biblib/query/MaFX6tuGSaWumxjrm4ri2A\",\n",
    "                        headers={'Authorization': 'Bearer ' + token},\n",
    "                        data=json.dumps(payload))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "# remove the bibcode by query\n",
    "payload = {\"params\": {\"q\": \"black holes\", \n",
    "                      \"fq\": \"database:astronomy\"}, \n",
    "           \"action\": \"remove\"}\n",
    "results = requests.post(\"https://api.adsabs.harvard.edu/v1/biblib/query/MaFX6tuGSaWumxjrm4ri2A\",\n",
    "                        headers={'Authorization': 'Bearer ' + token},\n",
    "                        data=json.dumps(payload))"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### GET\n",
    "Add a document to a given library. Returns the number of documents added along with a list of added bibcodes\n",
    "\n",
    "The `GET` request for this endpoint can only be used to add documents to the library. For removal by query, see the `POST` request above.\n",
    "\n",
    "  * Query of the form:  `<biblib_API_url>/query/<library_id>?q=<query>&<additional_params>` \n",
    "    * See the Search notebook for more details and query examples.\n",
    "    * It is important to note that there is no `/` between the `library_id` and the query string (`?q=<query>`).\n",
    "\n",
    "*Return data*:\n",
    "  * number_added: (integer) number of documents added\n",
    "  * bibcodes: (list) list of added bibcodes\n",
    "\n",
    "*Permissions*:\n",
    "The following type of user can add or remove documents:\n",
    "  * owner\n",
    "  * admin\n",
    "  * write"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "# add a query with a GET request\n",
    "results = requests.get(\"https://api.adsabs.harvard.edu/v1/biblib/query/MaFX6tuGSaWumxjrm4ri2A?q=black+holes&fq=database:astronomy\",\n",
    "                       headers={'Authorization': 'Bearer ' + token})"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### /permissions/&lt;library_id&gt;\n",
    "Edit the permissions of a library. The `library_id` (string) is the unique identifier of the library, as specified in the `/libraries` GET response.\n",
    "\n",
    "#### GET\n",
    "Get the permissions for a given library.\n",
    "\n",
    "The response is a list of dictionaries, where each dictionary is for a specific user. The dictionary contains a list of all the permissions of the user:\n",
    "  \t* user dictionary (dict) contains:\n",
    "  \t\t* key (string): user e-mail\n",
    "  \t\t* item (list): list of permissions ('read', 'write', 'admin', 'owner')\n",
    "\n",
    "*Permissions*:\n",
    "The following type of user can access permissions of a library:\n",
    "  - owner\n",
    "  - admin"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "scrolled": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'kelly.lockhart@cfa.harvard.edu': ['owner']}]"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# get the library permissions\n",
    "results = requests.get(\"https://api.adsabs.harvard.edu/v1/biblib/permissions/h1j8YE_hTvSVZT7rWhrDXQ\",\n",
    "                       headers={'Authorization': 'Bearer ' + token})\n",
    "results.json()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### POST\n",
    "Edit the permissions of a library.\n",
    "\n",
    "Specify that the request is a POST method. You must include a payload, passed via the `data` keyword, in JSON format. The payload must include:\n",
    "  * email: (string) specifies which user's permissions to be modified\n",
    "  * permission: (dict) specifies the permissions type and whether the user has this permission\n",
    "   - allowed keys: (string) 'read', 'write', or 'admin'\n",
    "   - allowed values: (boolean) whether the user has this permission (true=yes, false=no)\n",
    "\n",
    "There is no response to the request.\n",
    "\n",
    "Note: An email will be sent to the affected user upon a successful permissions change.\n",
    "\n",
    "*Permissions*:\n",
    "The following type of user can update a permission for a user for a given library:\n",
    "  - owner\n",
    "  - admin"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{}"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# edit the library permissions\n",
    "payload = {\"email\":\"test@email.com\", \n",
    "           \"permission\": {\"read\": True}}\n",
    "results = requests.post(\"https://api.adsabs.harvard.edu/v1/biblib/permissions/h1j8YE_hTvSVZT7rWhrDXQ\",\n",
    "                        headers={'Authorization': 'Bearer ' + token},\n",
    "                        data=json.dumps(payload))\n",
    "results.json()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### /transfer/&lt;library_id&gt;\n",
    "Transfer a the ownership of a library to another ADS user. The `library_id` (string) is the unique identifier of the library, as specified in the `/libraries` GET response.\n",
    "\n",
    "#### POST\n",
    "Transfer the ownership of a library from one user to another. \n",
    "\n",
    "Specify that the request is a POST method. You must include a payload, passed via the `data` keyword, in JSON format. The payload must include:\n",
    "  * email: (string) email of the user the account should be transfered to\n",
    "\n",
    "There is no response to the request.\n",
    "\n",
    "Note: An email will be sent to the affected user upon a successful permissions change.\n",
    "\n",
    "*Permissions*:\n",
    "The following type of user can transfer libraries:\n",
    "  - owner"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{}"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# transfer the library ownership\n",
    "payload = {\"email\": \"test@email.com\"}\n",
    "results = requests.post(\"https://api.adsabs.harvard.edu/v1/biblib/transfer/h1j8YE_hTvSVZT7rWhrDXQ\",\n",
    "                        headers={'Authorization': 'Bearer ' + token},\n",
    "                        data=json.dumps(payload))\n",
    "results.json()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.6"
  },
  "vscode": {
   "interpreter": {
    "hash": "31f2aee4e71d21fbe5cf8b01ff0e069b9275f58929596ceb00d14d90e3e16cd6"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}