API_documentation_UNIXshell/Libraries_API.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.\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",
    "Note that the complete curl request should also include your personal API access token, as described in the top-level [README](https://github.com/adsabs/adsabs-dev-api/blob/master/README.md).\n",
    "\n",
    "The API examples in this notebook generally assume you're using `curl` statements from the shell command line--you'll see `%%bash` at the top of a cell if its contents should be run in the shell instead of in Python. Guidelines for translating bash `curl` statements into Python can be found in the [converting curl to python notebook](Converting_curl_to_python.ipynb). If you prefer, you can use the unofficial Python package instead; see the top-level [README](https://github.com/adsabs/adsabs-dev-api/blob/master/README.md) for more information."
   ]
  },
  {
   "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": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "100    30  100    30    0     0    240      0 --:--:-- --:--:-- --:--:--   252\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\n",
      "  \"error\": \"Unauthorized\"\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "curl -H \"Authorization: Bearer $token\" https://api.adsabs.harvard.edu/v1/biblib/libraries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "100    30  100    30    0     0    240      0 --:--:-- --:--:-- --:--:--   252\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\n",
      "  \"error\": \"Unauthorized\"\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "curl -H \"Authorization: Bearer $token\" https://api.adsabs.harvard.edu/v1/biblib/libraries/?start=0&rows=11&sort=date_created&order=asc"
   ]
  },
  {
   "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 using `-X POST`. The POST payload must also be passed using the `-d` flag and should be in JSON format. 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",
    "To indicate that the payload is in JSON format, you must include a header specifying the format: `-H \"Content-Type: application/json\"`.\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": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "100   173  100    30  100   143    322   1537 --:--:-- --:--:-- --:--:--  1965\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\n",
      "  \"error\": \"Unauthorized\"\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "curl -H \"Authorization: Bearer $token\" -H \"Content-Type: application/json\" \\\n",
    "    https://api.adsabs.harvard.edu/v1/biblib/libraries \\\n",
    "    -X POST \\\n",
    "    -d '{\"name\":\"API library\", \"description\":\"This library is created via API\", \"public\":true, \"bibcode\":[\"1975CMaPh..43..199H\",\"1973PhRvD...7.2333B\"]}'\n"
   ]
  },
  {
   "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/&lt;library_id&gt;` 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": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "100    30  100    30    0     0    219      0 --:--:-- --:--:-- --:--:--   232\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\n",
      "  \"error\": \"Unauthorized\"\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "# get the data for the library created above\n",
    "# note: add | python -m json.tool to the end of the request to print the response in a more readable format\n",
    "curl -H \"Authorization: Bearer $token\" https://api.adsabs.harvard.edu/v1/biblib/libraries/hHGU1Ef-TpacAhicI3J8kQ | python -m json.tool"
   ]
  },
  {
   "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": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "100   831  100   831    0     0   1728      0 --:--:-- --:--:-- --:--:--  1742\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\n",
      "    \"documents\": [\n",
      "        \"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",
      "    ],\n",
      "    \"solr\": \"Only the raw library was requested.\",\n",
      "    \"metadata\": {\n",
      "        \"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",
      "    },\n",
      "    \"updates\": {}\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "# get the data for the library created above\n",
    "# note: add | python -m json.tool to the end of the request to print the response in a more readable format\n",
    "curl -H \"Authorization: Bearer $token\" https://api.adsabs.harvard.edu/v1/biblib/libraries/Os2mtOH-RNiNyBWdSj0m2A?raw=true | python -m json.tool"
   ]
  },
  {
   "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 by adding `-X POST` to your request. You must include a payload, passed via the `-d` flag, in JSON format. Add this header to your request to indicate your payload is in the appropriate format: `-H \"Content-Type: application/json\"`. 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": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\"id\": \"BeUbSWXtTPCaRhRV3nec_w\", \"bibcode\": [\"2009A&A...502..515G\", \"2011ApJ...734...87R\", \"2010ApJ...710..248C\", \"2003ApJ...595..665X\", \"2011ApJ...731L..12S\", \"2010ApJ...721..505R\", \"2010ApJ...710L.156R\", \"2010ApJ...723.1255R\", \"2006ApJ...639L..51A\", \"2001AJ....122.2993S\", \"2010ASPC..423..355R\", \"2010A&A...518A..59G\", \"2010ApJ...721L..48K\"], \"description\": \"Union of 891661ca-1bda-4967-b4b9-6c1c5cab7bef with [u'rdRs4g4AQ522k9TJ2umtVA', u's56fjycaRMKxw6tDEr31XQ']\", \"name\": \"New union library\"}\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "\r\n",
      "  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\r\n",
      "100   613  100   498  100   115    498    115  0:00:01 --:--:--  0:00:01  2043\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "# take the union of 3 libraries, using the default description and public settings\n",
    "curl -H \"Authorization: Bearer $token\" -H \"Content-Type: application/json\" \\\n",
    "    https://api.adsabs.harvard.edu/v1/biblib/libraries/operations/iRZhyhvaSWe0uWwcXKt77w \\\n",
    "    -X POST \\\n",
    "    -d '{\"action\": \"union\", \"libraries\": [\"rdRs4g4AQ522k9TJ2umtVA\", \"s56fjycaRMKxw6tDEr31XQ\"], \"name\": \"New union library\"}'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\"id\": \"8V8DzNqyQuOyTX6RF9x7qQ\", \"bibcode\": [\"2001AJ....122.2993S\", \"2009A&A...502..515G\", \"2006ApJ...639L..51A\", \"2010ApJ...710..248C\", \"2003ApJ...595..665X\", \"2010A&A...518A..59G\", \"2011ApJ...731L..12S\"], \"description\": \"Sample intersection library\", \"name\": \"New intersection library\"}\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "\r\n",
      "  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\r\n",
      "  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\r\n",
      "100   438  100   289  100   149    289    149  0:00:01 --:--:--  0:00:01  2147\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "# take the intersection of 2 libraries, using the default public settings\n",
    "curl -H \"Authorization: Bearer $token\" -H \"Content-Type: application/json\" \\\n",
    "    https://api.adsabs.harvard.edu/v1/biblib/libraries/operations/BeUbSWXtTPCaRhRV3nec_w \\\n",
    "    -X POST \\\n",
    "    -d '{\"action\": \"intersection\", \"libraries\": [\"rdRs4g4AQ522k9TJ2umtVA\"], \"name\": \"New intersection library\", \"description\": \"Sample intersection library\"}'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\"id\": \"9KBh8sVHQxaVkoPALtoXgg\", \"bibcode\": [\"2011ApJ...734...87R\", \"2010ApJ...723.1255R\", \"2010ApJ...710L.156R\", \"2010ASPC..423..355R\", \"2010ApJ...721L..48K\", \"2010ApJ...721..505R\"], \"description\": \"Sample difference library\", \"name\": \"New difference library\"}\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "\r\n",
      "  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\r\n",
      "100   421  100   262  100   159    262    159  0:00:01 --:--:--  0:00:01  2170\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "# take the difference of 2 libraries\n",
    "curl -H \"Authorization: Bearer $token\" -H \"Content-Type: application/json\" \\\n",
    "    https://api.adsabs.harvard.edu/v1/biblib/libraries/operations/BeUbSWXtTPCaRhRV3nec_w \\\n",
    "    -X POST \\\n",
    "    -d '{\"action\": \"difference\", \"libraries\": [\"rdRs4g4AQ522k9TJ2umtVA\"], \"name\": \"New difference library\", \"description\": \"Sample difference library\", \"public\": true}'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\"public\": true, \"bibcode\": [], \"name\": \"New difference library\", \"description\": \"Sample difference library\"}\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "\r\n",
      "  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\r\n",
      "100   129  100   110  100    19    110     19  0:00:01 --:--:--  0:00:01   689\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "# empty a library of all of its bibcode contents\n",
    "curl -H \"Authorization: Bearer $token\" -H \"Content-Type: application/json\" \\\n",
    "    https://api.adsabs.harvard.edu/v1/biblib/libraries/operations/9KBh8sVHQxaVkoPALtoXgg \\\n",
    "    -X POST \\\n",
    "    -d '{\"action\": \"empty\"}'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\"public\": true, \"bibcode\": [\"2009A&A...502..515G\", \"2010ApJ...710L.156R\", \"2010ApJ...710..248C\", \"2003ApJ...595..665X\", \"2011ApJ...731L..12S\", \"2010ApJ...721..505R\", \"2011ApJ...734...87R\", \"2010ApJ...723.1255R\", \"2006ApJ...639L..51A\", \"2001AJ....122.2993S\", \"2010ASPC..423..355R\", \"2010A&A...518A..59G\", \"2010ApJ...721L..48K\"], \"name\": \"New difference library\", \"description\": \"Sample difference library\"}\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "\r\n",
      "  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\r\n",
      "100   466  100   407  100    59    407     59  0:00:01 --:--:--  0:00:01  2858\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "# copy the bibcode contents from the primary library to the secondary library (this will not empty the library first)\n",
    "curl -H \"Authorization: Bearer $token\" -H \"Content-Type: application/json\" \\\n",
    "    https://api.adsabs.harvard.edu/v1/biblib/libraries/operations/BeUbSWXtTPCaRhRV3nec_w \\\n",
    "    -X POST \\\n",
    "    -d '{\"action\": \"copy\", \"libraries\": [\"9KBh8sVHQxaVkoPALtoXgg\"]}'"
   ]
  },
  {
   "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 by adding `-X POST` to your request. You must include a payload, passed via the `-d` flag, in JSON format. Add this header to your request to indicate your payload is in the appropriate format: `-H \"Content-Type: application/json\"`. 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": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "100   144  100    68  100    76    223    250 --:--:-- --:--:-- --:--:--   483\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\"invalid_identifiers\": [\"2018cga..prop.5QPWP\"], \"number_added\": 1}\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "# add a bibcode\n",
    "curl -H \"Authorization: Bearer $token\" -H \"Content-Type: application/json\" \\\n",
    "    https://api.adsabs.harvard.edu/v1/biblib/documents/6TI2c01jSYe1WT0xNmw-vw \\\n",
    "    -X POST \\\n",
    "    -d '{\"bibcode\": [\"2018cxo..prop.5543P\", \"2018cga..prop.5QPWP\"], \"action\": \"add\"}'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "100   115  100    59  100    56    362    343 --:--:-- --:--:-- --:--:--   727\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\"number_removed\": 1, \"bibcodes\": [\"2018cxo..prop.5543P\"]}\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "# remove it again\n",
    "curl -H \"Authorization: Bearer $token\" -H \"Content-Type: application/json\" \\\n",
    "    https://api.adsabs.harvard.edu/v1/biblib/documents/6TI2c01jSYe1WT0xNmw-vw \\\n",
    "    -X POST \\\n",
    "    -d '{\"bibcode\": [\"2018cxo..prop.5543P\"], \"action\": \"remove\"}'"
   ]
  },
  {
   "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 by adding `-X PUT` to your request. You must also include a payload, passed via the `-d` flag, in JSON format. Add this header to your request to indicate your payload is in the appropriate format: `-H \"Content-Type: application/json\"`. 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": 11,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\"description\": \"New API library description\", \"name\": \"New API library name\", \"public\": false}\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "\r\n",
      "  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\r\n",
      "100   191  100    96  100    95     96     95  0:00:01 --:--:--  0:00:01   313\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "# change the metadata of a library\n",
    "curl -H \"Authorization: Bearer $token\" -H \"Content-Type: application/json\" \\\n",
    "    https://api.adsabs.harvard.edu/v1/biblib/documents/hHGU1Ef-TpacAhicI3J8kQ \\\n",
    "    -X PUT \\\n",
    "    -d '{\"name\": \"New API library name\", \"description\": \"New API library description\", \"public\": false}'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### DELETE\n",
    "Delete the given library\n",
    "\n",
    "Make sure to specify the DELETE method using `-X DELETE`. 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": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\"id\": \"GPdVMFKwTmC87ysCk3JK3g\", \"description\": \"My ADS library\", \"name\": \"temp library\"}\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "\r\n",
      "  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\r\n",
      "100   113  100    90  100    23     90     23  0:00:01 --:--:--  0:00:01   379\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "# create a temporary library\n",
    "curl -H \"Authorization: Bearer $token\" -H \"Content-Type: application/json\" \\\n",
    "    https://api.adsabs.harvard.edu/v1/biblib/libraries \\\n",
    "    -X POST \\\n",
    "    -d '{\"name\":\"temp library\"}'\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{}\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "\r\n",
      "  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\r\n",
      "100     3  100     3    0     0      3      0  0:00:01 --:--:--  0:00:01    10\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "# delete the temporary library\n",
    "curl -H \"Authorization: Bearer $token\" -H \"Content-Type: application/json\" \\\n",
    "    https://api.adsabs.harvard.edu/v1/biblib/documents/GPdVMFKwTmC87ysCk3JK3g \\\n",
    "    -X DELETE"
   ]
  },
  {
   "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 by adding `-X POST` to your request. You must include a payload, passed via the `-d` flag, in JSON format. Add this header to your request to indicate your payload is in the appropriate format: `-H \"Content-Type: application/json\"`. 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": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "100   342  100   265  100    77     59     17  0:00:04  0:00:04 --:--:--    77\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\"number_added\": 10, \"bibcodes\": [\"1973PhRvD...7.2333B\", \"2023MNRAS.518.1057E\", \"1977MNRAS.179..433B\", \"2016PhRvL.116f1102A\", \"1975CMaPh..43..199H\", \"1976PhRvD..14..870U\", \"2013ARA&A..51..511K\", \"2022RAA....22l2002S\", \"1973A&A....24..337S\", \"1974Natur.248...30H\"]}\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "# add a query by posting search parameters\n",
    "curl -H \"Authorization: Bearer $token\" -H \"Content-Type: application/json\" \\\n",
    "    https://api.adsabs.harvard.edu/v1/biblib/query/6TI2c01jSYe1WT0xNmw-vw \\\n",
    "    -X POST \\\n",
    "    -d '{\"params\": {\"q\": \"black holes\", \"fq\": \"database:astronomy\"}, \"action\": \"add\"}'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "100   347  100   267  100    80    978    293 --:--:-- --:--:-- --:--:--  1299\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\"number_removed\": 10, \"bibcodes\": [\"1973PhRvD...7.2333B\", \"2023MNRAS.518.1057E\", \"1977MNRAS.179..433B\", \"2016PhRvL.116f1102A\", \"1975CMaPh..43..199H\", \"1976PhRvD..14..870U\", \"2013ARA&A..51..511K\", \"2022RAA....22l2002S\", \"1973A&A....24..337S\", \"1974Natur.248...30H\"]}\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "# remove the bibcode by query\n",
    "curl -H \"Authorization: Bearer $token\" -H \"Content-Type: application/json\" \\\n",
    "    https://api.adsabs.harvard.edu/v1/biblib/query/6TI2c01jSYe1WT0xNmw-vw \\\n",
    "    -X POST \\\n",
    "    -d '{\"params\": {\"q\": \"black holes\", \"fq\": \"database:astronomy\"}, \"action\": \"remove\"}'"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "#### 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": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "100   265  100   265    0     0    506      0 --:--:-- --:--:-- --:--:--   510\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\"number_added\": 10, \"bibcodes\": [\"1973PhRvD...7.2333B\", \"2023MNRAS.518.1057E\", \"1977MNRAS.179..433B\", \"2016PhRvL.116f1102A\", \"1975CMaPh..43..199H\", \"1976PhRvD..14..870U\", \"2013ARA&A..51..511K\", \"2022RAA....22l2002S\", \"1973A&A....24..337S\", \"1974Natur.248...30H\"]}\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "# add a query with a GET request\n",
    "curl -H \"Authorization: Bearer $token\" \\\n",
    "    https://api.adsabs.harvard.edu/v1/biblib/query/6TI2c01jSYe1WT0xNmw-vw?q=black+holes&fq=database:astronomy "
   ]
  },
  {
   "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": 14,
   "metadata": {
    "scrolled": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[{\"test.user-api@example.email.com\": [\"owner\"]}]\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "\r\n",
      "  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\r\n",
      "100    52  100    52    0     0     52      0  0:00:01 --:--:--  0:00:01   201\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "# get the library permissions\n",
    "curl -H \"Authorization: Bearer $token\" \\\n",
    "    https://api.adsabs.harvard.edu/v1/biblib/permissions/hHGU1Ef-TpacAhicI3J8kQ  "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### POST\n",
    "Edit the permissions of a library.\n",
    "\n",
    "Specify that the request is a POST method by adding `-X POST` to your request. You must include a payload, passed via the `-d` flag, in JSON format. Add this header to your request to indicate your payload is in the appropriate format: `-H \"Content-Type: application/json\"`. 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": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{}\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "\r\n",
      "  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\r\n",
      "100    67  100     3  100    64      3     64  0:00:01 --:--:--  0:00:01   179\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "# edit the library permissions\n",
    "curl -H \"Authorization: Bearer $token\" -H \"Content-Type: application/json\" \\\n",
    "    https://api.adsabs.harvard.edu/v1/biblib/permissions/hHGU1Ef-TpacAhicI3J8kQ \\\n",
    "    -X POST \\\n",
    "    -d '{\"email\":\"test.user-api@example.email.com\", \"permission\": {\"read\": true}}'"
   ]
  },
  {
   "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 by adding `-X POST` to your request. You must include a payload, passed via the `-d` flag, in JSON format. Add this header to your request to indicate your payload is in the appropriate format: `-H \"Content-Type: application/json\"`. 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": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{}\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
      "                                 Dload  Upload   Total   Spent    Left  Speed\n",
      "\r\n",
      "  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0\r\n",
      "100    46  100     3  100    43      3     43  0:00:01 --:--:--  0:00:01   133\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "token=\"your-token-here\"\n",
    "# transfer the library ownership\n",
    "curl -H \"Authorization: Bearer $token\" -H \"Content-Type: application/json\" \\\n",
    "    https://api.adsabs.harvard.edu/v1/biblib/transfer/hHGU1Ef-TpacAhicI3J8kQ \\\n",
    "    -X POST \\\n",
    "    -d '{\"email\": \"test.user@example.email.com\"}'"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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
}