{"id":19858275,"url":"https://github.com/tuya/connector","last_synced_at":"2025-05-02T02:30:55.117Z","repository":{"id":45068664,"uuid":"364156254","full_name":"tuya/connector","owner":"tuya","description":"The connector framework maps cloud APIs to local APIs based on simple configurations and flexible extension mechanisms. You can subscribe to the distribution of cloud messages as local events. You can put all the focus on business logic without taking care of server-side programming nor relational databases. The OpenAPI or message subscription process is simplified, so you can focus on service logic and promote development efficiency.","archived":false,"fork":false,"pushed_at":"2025-01-17T09:30:34.000Z","size":2080,"stargazers_count":18,"open_issues_count":2,"forks_count":7,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-06T21:22:38.024Z","etag":null,"topics":["api-client","connector","iot","openapi","rest-api","rest-client","restful","retrofit","retrofit2","tuya"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tuya.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-05-04T06:06:19.000Z","updated_at":"2025-03-31T08:27:06.000Z","dependencies_parsed_at":"2024-11-12T14:23:08.180Z","dependency_job_id":"cb807267-8957-4a16-8091-7ae9dda67fbd","html_url":"https://github.com/tuya/connector","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuya%2Fconnector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuya%2Fconnector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuya%2Fconnector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuya%2Fconnector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tuya","download_url":"https://codeload.github.com/tuya/connector/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251972449,"owners_count":21673606,"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-client","connector","iot","openapi","rest-api","rest-client","restful","retrofit","retrofit2","tuya"],"created_at":"2024-11-12T14:22:38.137Z","updated_at":"2025-05-02T02:30:53.171Z","avatar_url":"https://github.com/tuya.png","language":"Java","readme":"[English](README.md) | [中文版](README_zh.md)\n\n[![License: Apache 2](https://img.shields.io/badge/license-Apache%202-green)](https://github.com/tuya/tuya-connector/blob/master/LICENSE 'License')\n![Version: 1.0.0](https://img.shields.io/badge/version-1.0.0-blue)\n\n\nThe `connector` framework maps cloud APIs to local APIs based on simple configurations and flexible extension mechanisms. You can subscribe to the distribution of cloud messages as local events. You can put all the focus on business logic without taking care of server-side programming nor relational databases. The OpenAPI or message subscription process is simplified, so you can focus on service logic and promote development efficiency.\n\n### Quick start ([tuya-spring-boot-starter](https://github.com/tuya/tuya-connector) recommended for cloud development)\n\n#### Integrate Spring Boot (recommended)\n\n1. Configure API data source.\n```\nconnector.api.base-url=https://www.xxx.com\n```\n\n2. Define the `Connector` API, add a scanning path, and then inject `Connector`.\n```java\n@ConnectorScan(basePackages = \"com.xxx.connector\")\n@SpringBootApplication\npublic class DemoApplication {\n    public static void main(String[] args) {\n        SpringApplication.run(DemoApplication.class, args);\n    }\n}\n\npublic interface Connector {\n    @GET(\"/test/{s}\")\n    String test(@Path(\"s\") String s);\n}\n\n@Service\npublic class Service {\n    @Autowired\n    private Connector connector;\n    \n    public String test(String s) {\n    \treturn connector.test(s);\t\n    }\n}\n```\n\n#### Configure a generic Java project\nCreate a `ConnectorFactory` based on the data source configurations, load `Connector` with `ConnectorFactory` to get the `Connector` proxy, and then make API requests by using the `Connector` proxy class.\n```java\npublic interface Connector {\n    @GET(\"/test/{s}\")\n    String test(@Path(\"s\") String s);\n}\n\npublic class Demo {\n\tpublic static void main(String[] args) {\n        // initialize configuration\n        Configuration config = new Configuration();\n        ApiDataSource dataSource = ApiDataSource.DEFAULT_BUILDER.build();\n        dataSource.setBaseUrl(\"https://www.xxx.com\");\n        config.setApiDataSource(dataSource);\n\n        // create ConnectorFactory\n        ConnectorFactory connectorFactory = new DefaultConnectorFactory(config);\n\n        // Load connector and create connector proxy\n        connector = connectorFactory.loadConnector(Connector.class);\n\n        // call API\n        String result = connector.test(\"hello\");\n    }\n}\n```\n\n\n### Features\n- Centralized management of headers.\n- Automatically gets and refreshes tokens.\n- Return values are compatible with camel case and underscores (_).\n- Return values are compatible with the generics mode. The result or \u003cT\u003e`T` can be returned.\n- Processes error codes.\n- Supports the interceptor extension.\n- Exports a cloud RESTful API as a local RESTful API.\n- Distributes messages and events.\n\n### Design description\n1. The cloud RESTful API is mapped to the local `Connector` API. The local `Connector` API is declared with HTTP annotations. The framework creates a proxy for the `Connector` API at runtime to process calls to the cloud RESTful API.\n2. Retrofit 2 is used to process underlying requests. Similar to Retrofit 2 projects, cloud APIs are called by API operations and annotated methods.\n3. Flexible extension mechanisms are supported:\n   i. ContextManager\n   ii. TokenManager\n   iii. HeaderProcessor\n   iv. ErrorProcessor\n   v. ConnectorInterceptor\n4. The framework can be used to sequentially subscribe to the unified cloud messaging model, parse message data, identify and construct specific message events, and then distribute local events.\n\n### Architecture of the framework\n![Integration of the framework](src/main/resources/architect.jpg)\n![Integration and extensions](src/main/resources/integration\u0026extension.jpg)\n\n### Core module design\n\n#### API connector model\n![API connector model](src/main/resources/ddd.png)\n\n- **Config**\n\nIncludes the configuration items and integrated extensions, such as the URL connections, access key ID (AK) and secret access key (SK), timeout, connection pool, logs, TokenManager, HeaderProcessor, and ContextManager.\n\n- **Core**\n\nImplements cloud development with the Connector framework and provides the logic to process and respond to cloud RESTful API requests.\n\n- **Annotations**\n\nRESTful API annotations and parsing for cloud development. The following annotations are available: GET, POST, PUT, DELETE, Header, HeaderMap, Headers, Body, Query, QueryMap, Path, and Url.\n\n| **Annotation** | **Description** | **Example** |\n| --- | --- | --- |\n| GET | HTTP GET method | @GET(**\"/test/annotations/get\"**)\u003cbr /\u003eBoolean get(); |\n| POST | HTTP POST method | @POST(**\"/test/annotations/post\"**)\u003cbr /\u003eBoolean post(); |\n| PUT | HTTP PUT method | @PUT(**\"/test/annotations/put\"**)\u003cbr /\u003eBoolean put(); |\n| DELETE | HTTP DELETE method | @DELETE(**\"/test/annotations/delete\"**)\u003cbr /\u003eBoolean delete(); |\n| Path | Mapping of the path parameter in the request | @GET(**\"/test/annotations/path/{path_param}\"**)\u003cbr /\u003eString path(@Path(**\"path_param\"**) String pathParam); |\n| Query | Mapping between the method parameter and the query string of the request URL | @GET(**\"/test/annotations/query\"**)\u003cbr /\u003eString query(@Query(**\"param\"**) String param); |\n| QueryMap | Mapping between the method parameter and the query string of the request URL | @GET(**\"/test/annotations/queryMap\"**)\u003cbr /\u003eString queryMap(@QueryMap  Map\u003cString, Object\u003e map); |\n| Header | Mapping between the method parameter and the request header | @GET(**\"/test/annotations/header\"**)\u003cbr /\u003eString header(@Header(**\"headerKey\"**) String header); |\n| Headers | Mapping between the annotations parameter and the request headers | @Headers(**\"headerKey:headerValue\"**)\u003cbr /\u003e@GET(**\"/test/annotations/headers\"**)\u003cbr /\u003eString headers(); |\n| HeaderMap | Mapping between the method parameter and the request header | @GET(**\"/test/annotations/headerMap\"**)\u003cbr /\u003eString headerMap(@HeaderMap  Map\u003cString, String\u003e headerMap); |\n| Url | Mapping between the method parameter and the request URL | @GET \u003cbr /\u003eString url(@Url String url); |\n| Body | Mapping between the method parameter and the request body | @POST(**\"/test/annotations/body\"**)\u003cbr /\u003eString body(@Body Object body); |\n\n- Interceptor\u0026Extension\n\nThe extensions to the framework, including ConnectorInterceptor and ErrorProcessor.\n\n#### Messaging connector model\n![Messaging connector model](https://cdn.nlark.com/yuque/0/2021/png/130426/1617203258286-90a4e4df-e720-471d-bb27-d2dad8717954.png#align=left\u0026display=inline\u0026height=211\u0026margin=%5Bobject%20Object%5D\u0026name=image.png\u0026originHeight=422\u0026originWidth=746\u0026size=18514\u0026status=done\u0026style=none\u0026width=373)\n\n- MessageDataSource\n  The class to configure message data sources, such as the address, access key ID, and secret access key of the messages to be subscribed to.\n\n- MessageDispatcher\n  The message dispatcher that is used to listen for cloud messages and distribute local events in different messaging services.\n\n- MessageEvent\n  The type of message event. Each message is identified by `type`. The data structure is maintained by inheritance.\n\n### Modules\n- connector-api: connects to RESTful APIs.\n- connector-messaging: subscribes to cloud messages.\n- connector-spring: integrates with Spring.\n- connector-spring-boot: integrates with Spring Boot.\n- connector-assist: the assistant module to provide the unit test environment.\n\n### Function plan\n- Request parameters compatible with camel case and underscores (_)\n- Mock mechanism\n- Multiple data sources\n- Multilingual support\n- Circuit breaker and downgrade\n- Cache\n- Asynchronous processing\n- Automatic generation of local code based on OpenAPI and specific plug-ins.\n- Implementation for other programming languages","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuya%2Fconnector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftuya%2Fconnector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuya%2Fconnector/lists"}