Skip to content

Using the APIs

Jump to bottom
paulalbert1 edited this page Sep 27, 2022 · 35 revisions

ReCiter ships with a set of microservices, each of which accomplishes a function. For example, the /reciter/identity/ API allows you to update identity information in the Identity DynamoDB table.

Most experienced developers will choose to interact with ReCiter's APIs through the command line. To understand what the APIs are and how they function, developers can refer to this article and to the Swagger-based user interfaces.

Using Swagger

ReCiter is integrated with Swagger, a toolset that provides a user interface with helpful cues for how to interact with the application's RESTful APIs.

Upon navigating to the Swagger webpages, administrators can:

  • browse through the different APIs
  • review the data model associated with the API
  • select different parameters
  • input different values
  • click execute and see the resulting output in JSON format
  • view how the different selected parameters and values can be put together in the form of a Curl command or URL request

Identity controller

The following APIs come with the main ReCiter codebase.

/reciter/find/identity/by/uid/

  • Purpose: retrieve identity information from the Identity table in DynamoDB for a single identity
  • URL: https://[application-subdomain].[Amazon-region].elasticbeanstalk.com/swagger-ui/#/identity-controller/findByUidUsingGET
  • Key parameters:
    • uid - primary identifier for the user
    • fields - API supports the Squiggly filtering syntax, e.g., reCiterArticleFeatures.pmid,reCiterArticleFeatures.userAssertion, reCiterArticleFeatures[userAssertion], etc.
  • Step-by-step instructions:
    1. Go to the Swagger interface for ReCiter.
    2. Go to /reciter/find/identity/by/uid/
    3. Click "Try it out."
    4. Enter person's "uid" or user ID.
    5. Click execute.

https://github.com/wcmc-its/ReCiter/blob/master/files/ReCiter-RetrieveIdentity.gif

/reciter/find/identity/by/uids/

  • Purpose: retrieve identity information from DynamoDB for a single identity
  • URL: https://[application-subdomain].[Amazon-region].elasticbeanstalk.com/swagger-ui/#/identity-controller/findByUidsUsingGET
  • Key parameters:
    • uid - primary identifier for the user separated by comma
    • fields - API supports the Squiggly filtering syntax, e.g., reCiterArticleFeatures.pmid,reCiterArticleFeatures.userAssertion, reCiterArticleFeatures[userAssertion], etc.
  • Step-by-step instructions:
    1. Go to the Swagger interface for ReCiter.
    2. Go to /reciter/find/identity/by/uid/
    3. Click "Try it out."
    4. Enter person's "uid" or user ID.
    5. Click on the dash button to enter a second person.
    6. Enter that second person's uid.
    7. Click execute.

https://github.com/wcmc-its/ReCiter/blob/master/files/ReCiter-RetrieveIdentities.gif

/reciter/identity/

  • Purpose: update identity information in the Identity table in DynamoDB using POST
  • URL: https://[application-subdomain].[Amazon-region].elasticbeanstalk.com/swagger-ui/#/identity-controller/addIdentityUsingPOST
  • Key parameters: all fields in the Identity table
  • Step-by-step instructions:
    1. Go to the Swagger interface for ReCiter.
    2. Go to /reciter/identity/
    3. Click "Try it out."
    4. Enter JSON. See wiki article for a sample file.
    5. Click execute.

https://github.com/wcmc-its/ReCiter/blob/master/files/ReCiter-PostIdentity.gif

/reciter/save/identities/

  • Purpose: update identity information in the Identity table in DynamoDB for multiple users
  • URL: https://[application-subdomain].[Amazon-region].elasticbeanstalk.com/swagger-ui.html#operations-identity-controller-saveIdentitiesUsingPUT
  • Key parameters: all fields in the Identity table
  • Step-by-step instructions:
    1. Go to the Swagger interface for ReCiter.
    2. Go to /reciter/save/identities/
    3. Click "Try it out."
    4. Enter JSON. See Reciter-Identity repository for a sample file.
    5. Click execute.

https://github.com/wcmc-its/ReCiter/blob/master/files/ReCiter-PutIdentity.gif

/reciter/find/all/identity

  • Purpose: get all identities in the Identity table in DynamoDB for multiple users
  • URL: https://[application-subdomain].[Amazon-region].elasticbeanstalk.com/swagger-ui.html#identity-controller/findAllUsingGET
  • Key parameters: all users in the Identity table
  • Step-by-step instructions:
    1. Go to the Swagger interface for ReCiter.
    2. Go to /reciter/find/all/identity
    3. Click "Try it out."
    4. Click execute.
  • GIF not shown because it takes several minutes to execute.

ReCiter controller

The following APIs come with the main ReCiter codebase.

/reciter/retrieve/articles/by/uid

  • Purpose: Triggers system lookup of candidate publications for a given user. This sets into motion the construction of a query for an individual (e.g., Bales M[au]), retrieves PubMed articles, and, if configured, retrieves matching Scopus articles. Articles are stored in DynamoDB and not output via the API interface.
  • URL: https://[application-subdomain].[Amazon-region].elasticbeanstalk.com/swagger-ui/#/re-citer-controller/retrieveArticlesByUidUsingGET
  • Key parameters: The following options that can be passed in as parameters at runtime.
    • uid - unique institutional identifier associated with your target person; no default
    • retrievalRefreshFlag
      • Option #1: "ALL_PUBLICATIONS" reruns the search returning all publications
      • Option #2: "ONLY_NEWLY_ADDED_PUBLICATIONS" runs the search but only for publications that returned since the last time the search has been run; this option was put in place to allow institutions to easily run ReCiter on a daily basis for thousands of users without having re-retrieve all the existing articles
      • Option #3: "FALSE" does not do any new search and is largely pointless.
    • fields - API supports the Squiggly filtering syntax, e.g., reCiterArticleFeatures.pmid,reCiterArticleFeatures.userAssertion, reCiterArticleFeatures[userAssertion], etc.
  • Step-by-step instructions:
    1. Go to the Swagger interface for ReCiter.
    2. Go to /reciter/retrieve/articles/by/uid
    3. Click "Try it out."
    4. Enter person's "uid" or user ID.
    5. Optional: under retrievalRefreshFlag, you may choose if you want a complete, partial, or no refresh of existing articles for your user. The options are: ALL_PUBLCATIONS, ONLY_NEWLY_ADDED_PUBLICATIONS, and FALSE. The default is FALSE.
    6. Click execute.

https://github.com/wcmc-its/ReCiter/blob/master/files/ReCiter-Retrieval.gif

/reciter/feature-generator/by/uid

  • Purpose: The /reciter/feature-generator/by/uid API is intended for use by admins to display pending publications for dozens or even hundreds of users in a single view, allowing for more efficient review of pending publications
  • URL: https://[application-subdomain].[Amazon-region].elasticbeanstalk.com/swagger-ui.html#operations-re-citer-controller-runFeatureGeneratorUsingGET
  • Key parameters: The following options that can be passed in as parameters at runtime.
    • uid - unique institutional identifier associated with your target person; no default
    • totalStandardizedArticleScore - final standardized score on a scale of 1-10 for each candidate article for your target author; a score of 5 would only return articles that had a score of 5 or greater; the raw score (totalArticleScoreNonStandardized) is mapped to this score using the thresholds defined in the standardizedScoreMapping parameter in application.properties. If you do not select a score, the system defaults to only suggest articles that have a standardized score of greater than or equal to totalArticleScore-standardized-default.
    • useGoldStandard - assertions that your target author did or did not write an article are store in the GoldStandard table in DynamoDB. You have two options for electing how such assertions are used:
      • Option #1: AS_EVIDENCE - assertions are used during cluster scoring (as opposed to clustering); in cases where we know a candidate article was written by an author, the score of every other article in that cluster increases; in cases where we know a candidate article was not written by an author, the score of every other article in that cluster decreases
      • Option #2: FOR_TESTING_ONLY - assertions are not used during cluster scoring; they only come into play once it's time to determine whether an article is a true positive, false positive, true negative, or false negative
    • filterByFeedback - allows you to specify articles by the type of feedback you have on record in the GoldStandard table; you have the option to return varying combinations of articles that are accepted, rejected, and/or null
    • analysisRefreshFlag
      • Option #1: if "TRUE", ReCiter will re-compute analyses; this is useful if you're changing settings in application.properties
      • Option #2: if "FALSE", ReCiter will not re-compute its suggested publications unless there are no existing analyses as stored in DynamoDB's Analysis table and/or S3
    • retrievalRefreshFlag
      • Option #1: "ALL_PUBLICATIONS" reruns the search returning all publications
      • Option #2: "ONLY_NEWLY_ADDED_PUBLICATIONS" runs the search but only for publications that returned since the last time the search has been run; this option was put in place to allow institutions to easily run ReCiter on a daily basis for thousands of users without having re-retrieve all the existing articles
      • Option #3: "FALSE" does not do any new search
    • fields - API supports the Squiggly filtering syntax, e.g., reCiterArticleFeatures.pmid,reCiterArticleFeatures.userAssertion, reCiterArticleFeatures[userAssertion], etc.
  • Step-by-step instructions:
    1. Go to the Swagger interface for ReCiter.
    2. Go to /reciter/feature-generator/by/uid
    3. Click "Try it out."
    4. Enter person's "uid" or user ID.
    5. Optional: enter totalStandardizedArticleScore. This is the minimum score. The default is set to 7.
    6. Optional: select option in useGoldStandard. AS_EVIDENCE means that the API uses accepted articles to increase the score of articles in the same cluster and rejected articles to decrease the score of articles in the same cluster. The default selection is AS_EVIDENCE.
    7. Optional: select option in filterByFeedback. The options are: ALL, ACCEPTED_ONLY, ACCEPTED_AND_NULL, etc. The default is set to ALL.
    8. Optional: select option in analysisRefreshFlag. The options are: TRUE and FALSE. If TRUE is selected, the scoring (as opposed to the article retrieval) is recomputed.
    9. Optional: under retrievalRefreshFlag, you may choose if you want a complete, partial, or no refresh of existing articles for your user. The options are: ALL_PUBLCATIONS, ONLY_NEWLY_ADDED_PUBLICATIONS, and FALSE. The default is FALSE.
    10. Click execute.

https://github.com/wcmc-its/ReCiter/blob/master/files/ReCiter-FeatureGenerator.gif

/reciter/feature-generator/by/group

  • Purpose: The /reciter/feature-generator/by/group API is full-featured, intended for use by admins for returning pending suggestions for groups of individuals and displaying these results in a user interface that a librarian or department administrator can review. (It does not return articles that have been accepted or rejected.) Note that if you attempt to return candidate publications for too many individuals, the API may timeout. We have found that this threshold is around ~500 people.
  • URL: https://[application-subdomain].[Amazon-region].elasticbeanstalk.com/swagger-ui.html#operations-re-citer-controller-retrieveBulkFeatureGeneratorUsingGET
  • Key parameters: The following options that can be passed in as parameters at runtime.
    • totalStandardizedArticleScore - final standardized score on a scale of 1-10 for each candidate article for your target author; a score of 5 would only return articles that had a score of 5 or greater; the raw score (totalArticleScoreNonStandardized) is mapped to this score using the thresholds defined in the standardizedScoreMapping parameter in application.properties. If you do not select a score, the system defaults to only suggest articles that have a standardized score of greater than or equal to totalArticleScore-standardized-default.
    • maxArticlesPerPerson - allows you to specify the maximum number of pending articles returned per person
    • departmentalAffiliation - only return publications in cases where a scholar has one of any specified departmental affiliations (e.g., "Pediatrics"); note that the admin can select multiple items of the same type, e.g., "Infectious Diseases", "Medicine", "Pediatrics"
    • personType - only return publications in cases where a scholar has one of any specified person types (e.g, faculty, student)
    • organizationalAffiliation - only return publications in cases where a scholar has one of any specified organizational affiliation (e.g., "Weill Cornell Medicine")
  • Step-by-step instructions:
    1. Go to the Swagger interface for ReCiter.
    2. Go to /reciter/feature-generator/by/group
    3. Click "Try it out."
    4. Optional: filter by personType, organizationalAffiliation, and/or departmentalAffiliation.
    5. Specify the maxArticlesPerPerson.
    6. Specify the totalStandardizedArticleScore threshold.
    7. Input the API key.
    8. Click execute.

https://github.com/wcmc-its/ReCiter/blob/master/files/ReCiter-FeatureGeneratorBulk.gif

/reciter/article-retrieval/by/uid

  • Purpose: The /reciter/article-retrieval/by/uid API is intended for departments and others who are interested in publishing publication data on public-facing webpages. This API does not provide confidential information such as personal email or names of student mentees output by the feature generator API (see below). It will always take into account any existing accepted or rejected articles to improve the accuracy of scoring. Additionally, this API does not allow its user to request a retrieval or analysis refresh.
  • URL: https://[application-subdomain].[Amazon-region].elasticbeanstalk.com/swagger-ui.html#operations-re-citer-controller-runArticleRetrievalUsingGET
  • Key parameters: The following options that can be passed in as parameters at runtime.
    • uid - unique institutional identifier associated with your target person; no default
    • totalStandardizedArticleScore - final standardized score on a scale of 1-10 for each candidate article for your target author; a score of 5 would only return articles that had a score of 5 or greater; the raw score (totalArticleScoreNonStandardized) is mapped to this score using the thresholds defined in the standardizedScoreMapping parameter in application.properties. If you do not select a score, the system defaults to only suggest articles that have a standardized score of greater than or equal to totalArticleScore-standardized-default.
    • filterByFeedback - allows you to specify articles by the type of feedback you have on record in the GoldStandard table; you have the option to return varying combinations of articles that are accepted, rejected, and/or null
    • fields - API supports the Squiggly filtering syntax, e.g., reCiterArticleFeatures.pmid,reCiterArticleFeatures.userAssertion, reCiterArticleFeatures[userAssertion], etc.
  • Step-by-step instructions:
    1. Go to the Swagger interface for ReCiter.
    2. Go to /reciter/article-retrieval/by/uid
    3. Click "Try it out."
    4. Enter person's "uid" or user ID.
    5. Optional: enter totalStandardizedArticleScore. This is the minimum score. The default is set to 7.
    6. Optional: select option in filterByFeedback. The options are: ALL, ACCEPTED_ONLY, ACCEPTED_AND_NULL, etc. The default is set to ALL.
    7. Click execute.

https://github.com/wcmc-its/ReCiter/blob/master/files/ReCiter-RetrieveArticles.gif

/reciter/goldstandard/{uid}

  • Purpose: retrieve accepted and rejected PMIDs from the GoldStandard table in DynamoDB
  • URL: https://[application-subdomain].[Amazon-region].elasticbeanstalk.com/swagger-ui.html#retrieveGoldStandardByUidUsingGET
  • Key parameters:
    • uid - unique institutional identifier associated with your target person; no default
    • fields - API supports the Squiggly filtering syntax, e.g., reCiterArticleFeatures.pmid,reCiterArticleFeatures.userAssertion, reCiterArticleFeatures[userAssertion], etc.
  • Step-by-step instructions:
    1. Go to the Swagger interface for ReCiter.
    2. Go to /reciter/goldstandard
    3. Click "Try it out."
    4. Enter person's "uid" or user ID.
    5. Click execute.

https://github.com/wcmc-its/ReCiter/blob/master/files/ReCiter-RetrieveGoldStandard.gif

/reciter/goldstandard/ (POST)

  • Purpose: update accepted and rejected PMIDs and audit log in the GoldStandard table in DynamoDB for single user
  • URL: https://[application-subdomain].[Amazon-region].elasticbeanstalk.com/swagger-ui.html#updateGoldStandardUsingPOST
  • Key parameters:
    • goldStandardUpdateFlag
      • UPDATE - adds to existing data
      • REFRESH - deletes existing data entirely
      • DELETE - deletes existing data entirely and adds additional information
  • Step-by-step instructions:
    1. Go to the Swagger interface for ReCiter.
    2. Go to /reciter/goldstandard (POST)
    3. Click "Try it out."
    4. Enter JSON data. A sample file can be found here.
    5. OPTIONAL: set goldStandardUpdateFlag
    6. Click execute.

https://github.com/wcmc-its/ReCiter/blob/master/files/ReCiter-UpdateGoldStandard.gif

/reciter/goldstandard/ (PUT)

  • Purpose: update accepted and rejected PMIDs and audit log in the GoldStandard table in DynamoDB for multiple users
  • URL: https://[application-subdomain].[Amazon-region].elasticbeanstalk.com/swagger-ui/#/re-citer-controller/updateGoldStandardUsingPUT
  • Key parameters:
    • goldStandardUpdateFlag
      • UPDATE - adds to existing data
      • REFRESH - deletes existing data entirely
      • DELETE - deletes existing data entirely and adds additional information
  • Step-by-step instructions:
    1. Go to the Swagger interface for ReCiter.
    2. Go to /reciter/goldstandard (PUT)
    3. Click "Try it out."
    4. Enter JSON data. A sample file can be found here.
    5. Click execute.

https://github.com/wcmc-its/ReCiter/blob/master/files/ReCiter-UpdateGoldStandard-MultipleUsers.gif

Additional APIs

Clone this wiki locally