{"id":19876025,"url":"https://github.com/ernxst/api-connector","last_synced_at":"2025-03-01T01:41:00.015Z","repository":{"id":131364005,"uuid":"385616391","full_name":"Ernxst/API-Connector","owner":"Ernxst","description":"Handles the interaction between your application and other external APIs.","archived":false,"fork":false,"pushed_at":"2021-07-13T13:39:48.000Z","size":92,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-19T22:18:39.867Z","etag":null,"topics":["api","docker","json","json-api","json-schema","rest-api","restful-api"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ernxst.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-13T13:37:22.000Z","updated_at":"2021-07-13T14:54:06.000Z","dependencies_parsed_at":"2023-07-31T21:48:58.266Z","dependency_job_id":null,"html_url":"https://github.com/Ernxst/API-Connector","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ernxst%2FAPI-Connector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ernxst%2FAPI-Connector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ernxst%2FAPI-Connector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ernxst%2FAPI-Connector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ernxst","download_url":"https://codeload.github.com/Ernxst/API-Connector/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241304294,"owners_count":19941100,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","docker","json","json-api","json-schema","rest-api","restful-api"],"created_at":"2024-11-12T16:30:20.037Z","updated_at":"2025-03-01T01:40:59.998Z","avatar_url":"https://github.com/Ernxst.png","language":"Java","readme":"# API Connector Plugin\n\nThe API Connector Plugin package defines and handles the interaction between your app and other external RESTful APIs over HTTP(S).\nIt also performs its own error handling and output parsing.\n\n- It allows you to easily define and make API requests and then parses the JSON response into a natural language string,\n  defined by you.\n- Sample external API services are included as a demonstration.\n- New external service APIs can easily be added.\n\nFor use as a RESTful API (instead of native Java code, detailed below), more information can be found in the `api`\npackage [here](src/main/java/com/example/api).\n\n## Interface\n\nThe `makeRequest` method takes the service name and required data as parameters and performs the API request, the output\nis a sentence for the speech synthesiser to speak aloud to the user (with the relevant data included).\n\n- This output is put onto an API response queue, which is to be maintained by your app.\n\n\u003cpre\u003evoid makeRequest(String serviceName, HashMap \u0026lt;String, String\u0026gt; payload)\u003c/pre\u003e\n\nThe recognised service names are:\n\n- [_\"air quality\"_](#air-quality-api)\n- [_\"book\"_](#book-by-search-api)\n- [_\"charity search\"_](#charity-search-api)\n- [_\"charity by city\"_](#charity-by-city-api)\n- [_\"current weather\"_](#current-weather-api)\n- [_\"dictionary\"_](#dictionary-api)\n- [_\"ingredient\"_](#recipe-by-ingredient-api)\n- [_\"joke\"_](#joke-api)\n- [_\"nearest transport\"_](#nearest-transport-api)\n- [_\"news\"_](#news-api)\n- [_\"random recipe\"_](#random-recipe-api)\n- [_\"recipe\"_](#recipe-by-search-api)\n- [_\"recipe instructions\"_](#recipe-instructions-api)\n- [_\"stocks\"_](#stocks-api)\n- [_\"transport search\"_](#transport-by-search-api)\n- [_\"weather forecast\"_](#weather-forecast-api)\n\nNote that these can easily be added to.\n\n## Getting Responses\n\nThe API response queue should have the type:\n\n    BlockingQueue\u003cApiResponse\u003e appQueue;\n\nPeriodically polling this queue returns an `ApiResponse` object returning the service's response after a call is made.\n\nThe string response, suitable for speech synthesis, can be retrieved using the `getResponse()` method of the object.\n\nThe name of the service that was called can be retrieved using the `getName()` method of the object.\n\nA service may return (required) data that is not suitable for speech synthesis e.g. an image to display. This type of\ndata is referred to as _'metadata'_, stored in a `HashMap\u003cString, Object` named `metadata`. It is retrieved by calling\nthe `metadata()` method of an `ApiResponse` object.\n\n- Note that there is no standard for the representation of data inside the hashmap - this is entirely dependent on the\n  service, and its corresponding `parseOutput` method.\n- Expected metadata (for successful API calls) for relevant services is detailed below, **for that specific service\n  only**.\n\nThe `getName()` method should be used to check what service was returned to determine how to read its metadata, if\nrequired.\n\nAn example implementation showing how to retrieve responses can be found in test package.\n\nThe following section defines the required parameters needed by each service. See the [_\"Adding\nServices\"_](#adding-services) section for more information on how to integrate new com.\n\n## API Formats\n\nThe following set of tables define the required data needed by each service. The internal structure of a `REST`ful\nservice API request is a `HashMap\u003cString, String\u003e` object where the **Attribute** columns below represent the exact\nfield names in the hash map for a service.\n\n### Current Weather API\n\nA service allowing the user to retrieve information about the current weather in their (or explicitly specified) city.\n\n|   Attribute    | Type   |  Default   | Description                                                                                                                                                                                             |\n| :------------: | ------ | :--------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n|  `CITY_NAME`   | String | `\"London\"` | The name of the city the user's device is located in.                                                                                                                                                   |\n| `COUNTRY_CODE` | String |   `\"uk\"`   | The two-character ISO country code of the city. The full list of possible country codes can be found [here](https://countrycode.org/).                                                                  |\n|   `LANGUAGE`   | String |   `\"en\"`   | The two-character (or three) ISO code of the language to return the weather in. The full list of possible language codes can be found [here](https://www.loc.gov/standards/iso639-2/php/code_list.php). |\n\n### Weather Forecast API\n\nA service returning the predicted weather for the user's exact location.\n\n| Attribute  | Type    |   Default   | Description                                                                                                                                                                                             |\n| :--------: | ------- | :---------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n|   `LAT`    | Double  | `51.534121` | The latitude of the user's current (or most recent) location.                                                                                                                                           |\n|   `LON`    | Double  |  `-0.006`   | The longitude of the user's current (or most recent location.                                                                                                                                           |\n| `LANGUAGE` | String  |   `\"en\"`    | The two-character (or three) ISO code of the language to return the weather in. The full list of possible language codes can be found [here](https://www.loc.gov/standards/iso639-2/php/code_list.php). |\n|   `DAYS`   | Integer |     `1`     | The number of days to forecast for. The minimum is 7 and the maximum is 7.                                                                                                                              |\n\n### Air Quality API\n\nA service returning the air quality index for a given city.\n\n|  Attribute  | Type   |  Default   | Description                                           |\n| :---------: | ------ | :--------: | ----------------------------------------------------- |\n| `CITY_NAME` | String | `\"London\"` | The name of the city the user's device is located in. |\n\n### Stocks API\n\nA service allowing the user to retrieve stock information on an equity of their choice.\n\n| Attribute  | Type    |         Default          | Description                                                                                                                           |\n| :--------: | ------- | :----------------------: | ------------------------------------------------------------------------------------------------------------------------------------- |\n| `FUNCTION` | String  | `\"TIME_SERIES_INTRADAY\"` | The time series of your choice.                                                                                                       |\n|  `SYMBOL`  | String  |         `\"IBM\"`          | The name of the equity.                                                                                                               |\n| `INTERVAL` | Integer |           `1`            | Time interval between two consecutive data points in the time series. The following values are supported: `1`, `5`, `15`, `30`, `60`. |\n\n### Joke API\n\nA service retrieving a random or specific joke.\n\n| Attribute | Type   | Default | Description                           |\n| :-------: | ------ | :-----: | ------------------------------------- |\n|  `TERM`   | String |  `\"\"`   | The search term to search for a joke. |\n\n### Dictionary API\n\nA service retrieving the definition, examples and synonyms for a given word.\n\n|     Attribute      | Type    |  Default  | Description                                                                                                                                                                                                |\n| :----------------: | ------- | :-------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n|       `WORD`       | String  | `\"hello\"` | The word to retrieve the definition of.                                                                                                                                                                    |\n|     `LANGUAGE`     | String  |  `\"en\"`   | The two-character (or three) ISO code of the language to return the definition in. The full list of possible language codes can be found [here](https://www.loc.gov/standards/iso639-2/php/code_list.php). |\n| `INCLUDE_SYNONYMS` | Boolean | `\"false\"` | Indicates whether to retrieve the synonyms of the word as well.                                                                                                                                            |\n|  `SYNONYMS_ONLY`   | Boolean | `\"false\"` | Allows for thesaurus usage, retrieving only the synonyms of the word and not its definition and example sentence usage. If this is set to `true`, `INCLUDE_SYNONYMS` is also set to `true` by default.     |\n\n### Nearest Transport API\n\nThis service returns either the nearest train stations or bus stops for a given location range.\n\n|  Attribute  | Type   |      Default      | Description                                                                                       |\n| :---------: | ------ | :---------------: | ------------------------------------------------------------------------------------------------- |\n|  `MIN-LAT`  | Double |    `51.530121`    | The minimum latitude, representing one corner of the bounding box - must be less than `MAX-LAT`.  |\n|  `MAX-LAT`  | Double |    `51.538121`    | The maximum latitude, representing one corner of the bounding box - must be more than `MIN-LAT`.  |\n|  `MIN-LON`  | Double |     `-0.009`      | The minimum longitude, representing one corner of the bounding box - must be less than `MAX-LON`. |\n|  `MAX-LON`  | Double |     `-0.001`      | The maximum longitude, representing one corner of the bounding box - must be more than `MIN-LON`. |\n| `TRANSPORT` | String | `\"train_station\"` | Indicates whether to search for a train station (`train_station`) or a bus stop (`bus_stop`).     |\n\nNote that this service does not return any spoken output, just the coordinates of the nearest transport points defined\nbelow.\n\n#### Metadata\n\nThe metadata returned by this service contains just one top-level field - `locations` which is an array of latitude,\nlongitude pairs for each returned transport point. Each element in the `locations` array is a `Double[]` array, with the\nfollowing elements:\n\n|  Attribute  |   Type   | Description                           |\n| :---------: | :------: | ------------------------------------- |\n| `latitude`  | `Double` | The latitude of the transport point.  |\n| `longitude` | `Double` | The longitude of the transport point. |\n\nNote that the ordering here is important - **the first element in the array is the `latitude`, the second\nthe `longitude`**.\n\n### Transport By Search API\n\nThis service returns information on a bus stop or train station by its name.\n\n|  Attribute  | Type   |      Default      | Description                                                                                   |\n| :---------: | ------ | :---------------: | --------------------------------------------------------------------------------------------- |\n|   `QUERY`   | String |    `\"euston\"`     | The name of the train station or bus stop to search for.                                      |\n| `TRANSPORT` | String | `\"train_station\"` | Indicates whether to search for a train station (`train_station`) or a bus stop (`bus_stop`). |\n\n#### Metadata\n\nThe metadata returned by this service is:\n\n|  Attribute  |   Type   | Description                           |\n| :---------: | :------: | ------------------------------------- |\n| `latitude`  | `Double` | The latitude of the transport point.  |\n| `longitude` | `Double` | The longitude of the transport point. |\n\n### Random Recipe API\n\nThis service returns a random recipe.\n\nThis service requires no parameters - supplying them has no effect.\n\n#### Metadata\n\nThe metadata returned by this service is:\n\n|  Attribute  |   Type   | Description                                                                                                                                             |\n| :---------: | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `recipe-id` | `String` | The ID of the recipe, useful for further API calls, e.g., fetching the full instructions using the [recipe instructions API](#recipe-instructions-api). |\n|   `image`   | `String` | A URL to the cover image of the recipe.                                                                                                                 |\n\n### Recipe By Search API\n\nThis service returns a set of recipes by searching via natural language.\n\n| Attribute | Type   | Default | Description      |\n| :-------: | ------ | :-----: | ---------------- |\n|  `QUERY`  | String |  `\"\"`   | The search term. |\n\n#### Metadata\n\nThe metadata returned by this service is:\n\n|  Attribute  |   Type   | Description                                                                                                                                             |\n| :---------: | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `recipe-id` | `String` | The ID of the recipe, useful for further API calls, e.g., fetching the full instructions using the [recipe instructions API](#recipe-instructions-api). |\n|   `image`   | `String` | A URL to the cover image of the recipe.                                                                                                                 |\n\n### Recipe By Ingredient API\n\nThis service returns a set of recipes with certain ingredients, specified by the user.\n\n|   Attribute   | Type   | Default | Description                                            |\n| :-----------: | ------ | :-----: | ------------------------------------------------------ |\n| `INGREDIENTS` | String |  `\"\"`   | A comma separated string of ingredients to search for. |\n\n#### Metadata\n\nThe metadata returned by this service is:\n\n|  Attribute  |   Type   | Description                                                                                                                                             |\n| :---------: | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `recipe-id` | `String` | The ID of the recipe, useful for further API calls, e.g., fetching the full instructions using the [recipe instructions API](#recipe-instructions-api). |\n|   `image`   | `String` | A URL to the cover image of the recipe.                                                                                                                 |\n\n### Recipe Instructions API\n\nThis service returns the instructions for the recipes returned by the services above.\n\n| Attribute  | Type    | Default | Description                                                                                |\n| :--------: | ------- | :-----: | ------------------------------------------------------------------------------------------ |\n|    `ID`    | String  |  `\"\"`   | The ID of the recipe.                                                                      |\n| `DETAILED` | Boolean | `true`  | Whether to split instructions into steps (`true`) or return a plain description (`false`). |\n\nNote that this service is intended to be used _internally_ - each recipe service above returns the `ID` of the recipe in\nthe `metadata` of the response object; the recipe instructions service should then be used to retrieve the instructions\nof that recipe.\n\nThis service also returns no spoken output. The `metadata`, defined below, can be used to programmatically decide what\nsteps to read (instead of reading it all at once).\n\n#### Metadata\n\nThe metadata returned by this service is:\n\n| Attribute |        Type         | Description                                                                     |\n| :-------: | :-----------------: | ------------------------------------------------------------------------------- |\n|  `steps`  | `ArrayList\u003cString\u003e` | An array of instructions for the recipe - each element is one instruction step. |\n\n### News API\n\nThis service returns a news article based on the user's search.\n\n| Attribute  | Type   | Default | Description                                                                                                                                                                                              |\n| :--------: | ------ | :-----: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n|  `QUERY`   | String |  `\"\"`   | The search term, in natural language.                                                                                                                                                                    |\n| `LANGUAGE` | String | `\"en\"`  | The language to return the result in. Uses the two-character IS0-639-1 code scheme. The full list of possible language codes can be found [here](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). |\n\n#### Metadata\n\nThe metadata returned by this service is:\n\n| Attribute |   Type   | Description                              |\n| :-------: | :------: | ---------------------------------------- |\n|   `url`   | `String` | A URL to the full news article.          |\n|  `image`  | `String` | A URL to the cover image of the article. |\n\n### Charity Search API\n\nThis service returns information on a specified number of charities, based on the user's search in natural language.\n\n| Attribute | Type   | Default | Description                                                 |\n| :-------: | ------ | :-----: | ----------------------------------------------------------- |\n|  `QUERY`  | String |  `\"\"`   | The search term, in natural language.                       |\n| `VALUES`  | String |   `1`   | The (maximum) number of charities to return information on. |\n\n#### Metadata\n\nThe metadata returned by this service contains just one top-level field: `charities` which is an array of maps (each one\nrepresenting a charity) where each map contains the following information:\n\n|   Attribute   |   Type   | Description                             |\n| :-----------: | :------: | --------------------------------------- |\n|    `name`     | `String` | The name of the charity.                |\n|     `URL`     | `String` | A URL to the charity's registered page. |\n| `donationURL` | `String` | A URL to donate to the charity.         |\n|  `latitude`   | `Double` | The latitude of the charity.            |\n|  `longitude`  | `Double` | The longitude of the charity.           |\n\n### Charity By City API\n\nThis service returns information on a specified number of charities in a given city.\n\n| Attribute | Type    |  Default   | Description                                                 |\n| :-------: | ------- | :--------: | ----------------------------------------------------------- |\n|  `CITY`   | String  | `\"london\"` | The search term, in natural language.                       |\n| `VALUES`  | Integer |    `1`     | The (maximum) number of charities to return information on. |\n\n#### Metadata\n\nThe metadata returned by this service contains just one top-level field: `charities` which is an array of maps (each one\nrepresenting a charity) where each map contains the following information:\n\n|   Attribute   |   Type   | Description                             |\n| :-----------: | :------: | --------------------------------------- |\n|    `name`     | `String` | The name of the charity.                |\n|     `URL`     | `String` | A URL to the charity's registered page. |\n| `donationURL` | `String` | A URL to donate to the charity.         |\n|  `latitude`   | `Double` | The latitude of the charity.            |\n|  `longitude`  | `Double` | The longitude of the charity.           |\n\n### Book By Search API\n\nThis service returns information on a book based on the user's search.\n\n|  Attribute  | Type   | Default | Description                                                                                                                                                                                                                                 |\n| :---------: | ------ | :-----: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n|   `QUERY`   | String |  `\"\"`   | The search term, in natural language. Entirely optional.                                                                                                                                                                                    |\n|   `TOPIC`   | String |  `\"\"`   | A certain topic to look for. Entirely optional.                                                                                                                                                                                             |\n| `LANGUAGES` | String | `\"en\"`  | A comma separated string containing the list of languages to search for. Uses the two-character IS0-639-1 code scheme. The full list of possible language codes can be found [here](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). |\n\nNote that both the `QUERY` and `TOPIC` attributes are optional, but at least one must be supplied.\n\n#### Metadata\n\nThe metadata returned by this service is:\n\n|            Attribute             |   Type    | Description                                                               |\n| :------------------------------: | :-------: | ------------------------------------------------------------------------- |\n|               `id`               | `Integer` | The ID of the book, useful for making further API calls.                  |\n|           `image/jpeg`           | `String`  | A URL to the image of the book cover.                                     |\n|           `text/html`            | `String`  | A URL to an online version of the book, formatted with HTML.              |\n|         `text/plaintext`         | `String`  | A URL to an online version of the book, in plain text with no formatting. |\n| `application/x-mobipocket-ebook` | `String`  | A URL to an ebook download of the book.                                   |\n|      `application/epub+zip`      | `String`  | A URL to an ebook download of the book in a different format than above.  |\n\n## Adding Services\n\nThe API service interaction is highly extensible. There are two methods to adding new external service APIs, detailed\nbelow.\n\n### JSON Schema\n\nThe JSON schema allows for new service APIs to be added in a language-independent manner, providing a simple and\nintuitive, yet powerful interface.\n\nFull details on getting started with the schema can be found [here](src/main/java/com/example/services/schema/README.md)\n.\n\n- After following the instructions, no code needs to be modified to add the service.\n\nFor most use-cases, the JSON schema should be sufficient to perform and parse API calls. However, there are some\nlimitations with the schema; to circumvent these, the service can be implemented as a [Java class](#java-class).\n\n### Java Class\n\nShould you require more fine-grained control over the API URL, or the response parsing, it is recommended to do so using\na Java class.\n\nA service must extend the abstract `ServiceRequest` class, providing the following attributes:\n\n- `URL` - The URL where the resource provided by the API is located.\n- If the URL requires any named parameters, they are to be added in the following format:\n- _e.g. the [Weather API](#current-weather-api) requires a `lang` attribute: `...lang={LANGUAGE}` as per the **\n  Attribute** `LANGUAGE` in its API format._\n- `name` - The name of the service - **must be unique**.\n- `category` - The category the service falls under.\n- `APIKey` - A unique string used to access the service's API - this is obtained by registering for one on the API's\n  website. Pass an empty string if it is not required by the service.\n- `payload` - A `HashMap` containing the parameters required to perform the API request. The necessary keys (and values)\n  for each service are defined in the section [above](#api-formats).\n\nNote that the concrete service class must only take one parameter - the `payload`. The concrete constructor must be of\nthe form:\n\n    public NewServiceRequest(HashMap\u003cString, String\u003e payload) {\n        super(\"URL_HERE\", \"NAME_HERE\", \"CATEGORY_HERE\", \"API_Key_HERE\", payload);\n    }\n\nIt will then be called by the `ServiceFactory` as `new NewServiceRequest(payload);`\n\nIt must also implement the following methods:\n\n- `parseOutput(HashMap\u003cString, Object\u003e response);` - Defines how each service interprets its output from the API. This\n  is also where any metadata should be set.\n\n- `String handleErrors(HashMap\u003cString, Object\u003e response);` - Defines how each service interprets error messages from the\n  API.\n\n- `String getErrorCode(HashMap\u003cString, Object\u003e response);` - Defines how the HTTP error code is represented and\n  retrieved for each service. Each service API will have a different way of representing HTTP error codes.\n\n- `HashMap\u003cString, String\u003e populatePayload();` - Inserts default data into the payload if not given to avoid malformed\n  requests. This method is what applies the attributes from the API format to a service.\n\nThe service can then be called by adding its name to the switch statement in the `ServiceFactory` by adding a new case\nfor its `name` attribute in lowercase and returning a new object of the service (which takes the `payload` as its only\nparameter). No other code interaction needs to take place.\n\nThe service should be placed in the `com` package, in the relevant category package, defining a new package if it does\nnot fall into an existing category.\n\n### Documentation\n\nWith either extension method, please ensure to update the documentation accordingly after adding new com.\n\nThe new service's name should be add to the bullet [list of recognised service names](#interface), preferably to\nmaintain alphabetical order.\n\nThe new service's API format should also be listed in the [\"API Format\"](#api-formats) section with its description,\nparameters it takes (if applicable) and any metadata it returns.\n\nThe new service's name should also be added to the bullet list\nof [endpoints](src/main/java/com/example/api/README.md#endpoints) defined in the RESTful API package's README.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fernxst%2Fapi-connector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fernxst%2Fapi-connector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fernxst%2Fapi-connector/lists"}