Skip to content

Using the APIs

Jump to bottom
paulalbert1 edited this page Jan 20, 2019 · 35 revisions

ReCiter ships with a set of microservices, each of which accomplishes 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 comes 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.html#/identity-controller/findByUidUsingGET
  • Key parameters: uid (primary identifier for the user)
  • Step-by-step instructions:
      1. Go to the Swagger interface for ReCiter.
      1. Go to /reciter/find/identity/by/uid/
      1. Click "Try it out."
      1. Enter person's "uid" or user ID.
      1. 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.html#/identity-controller/findByUidsUsingGET
  • Key parameters: uids (primary identifier for the user) separated by comma
  • Step-by-step instructions:
      1. Go to the Swagger interface for ReCiter.
      1. Go to /reciter/find/identity/by/uid/
      1. Click "Try it out."
      1. Enter person's "uid" or user ID.
      1. Click on the dash button to enter a second person.
      1. Enter that second person's uid.
      1. Click execute.

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

/reciter/identity/

  • Purpose: update identity information in DynamoDB
  • URL: https://[application-subdomain].[Amazon-region].elasticbeanstalk.com/swagger-ui.html#/identity-controller/addIdentityUsingPOST
  • Key parameters: all fields in the Identity table

/reciter/save/identities/ (How is this different than above?)

  • Purpose: update identity information in DynamoDB
  • URL: https://[application-subdomain].[Amazon-region].elasticbeanstalk.com/swagger-ui.html#operations-identity-controller-saveIdentitiesUsingPUT
  • Key parameters: all fields in the Identity table

ReCiter controller

The following APIs come with the main ReCiter codebase.

/reciter/feature-generator/by/uid

  • Purpose: The /reciter/feature-generator/by/uid API is full-featured, intended for use by admins for testing accuracy of ReCiter or as a system-level integration with a user interface that displays evidence. It will optionally take into account any existing accepted or rejected articles to improve the accuracy of scoring.
  • 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
  • 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/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
  • 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

Gold standard

  • Purpose:
  • URL: https://[application-subdomain].[Amazon-region].elasticbeanstalk.com/swagger-ui.html
  • Key parameters:

Scopus

  • Purpose:
  • URL: https://[application-subdomain].[Amazon-region].elasticbeanstalk.com/swagger-ui.html
  • Key parameters:

PubMed

  • Purpose:
  • URL: https://[application-subdomain].[Amazon-region].elasticbeanstalk.com/swagger-ui.html
  • Key parameters:

/reciter/feature-generator/by/uid This api generates all the suggestion for a given uid along with its relevant evidence.

/reciter/goldstandard/ Update the goldstandard by passing GoldStandard model(uid, knownPmids, rejectedPmids)

/reciter/goldstandard/ Update the goldstandard by passing a list of GoldStandard model(uid, knownPmids, rejectedPmids) This api updates the goldstandard by passing list of GoldStandard model(uid, knownPmids, rejectedPmids).

/reciter/goldstandard/{uid} Get the goldStandard by passing an uid This api gets the goldStandard by passing an uid.

/reciter/retrieve/articles/ Retrieve Articles for all UID in Identity Table This API retrieves candidate articles for all uid in Identity Table from pubmed and its complementing articles from scopus

/reciter/retrieve/articles/by/uid Retrieve Articles for an UID. This API retrieves candidate articles for a given uid from pubmed and its complementing articles from scopus

Clone this wiki locally