Project: Apollo (Provisioning / Automation & Configuration)
File: other-language-client-user-guide.md

At present, Apollo team only provides Java and .Net clients due to manpower constraints. For applications in other languages, you can directly obtain the configuration through the Http interface through the introduction of this article. Also, if any team/individual is interested, they are welcome to help us to implement the client in other languages, please contact @nobodyiam and @lepdou for details. Note: There are already clients for Go, Python, NodeJS, PHP, C++ contributed by enthusiastic users, for more information you can refer to "SDK Guide" First you need to access your application in Apollo, you can refer to for the specific steps. This interface will fetch the configuration from the cache and is suitable for more frequent configuration pull requests, such as a simple polling of the configuration every 30 seconds. Since the cache has a delay of at most one second, if you need to work with configuration push notifications to achieve real-time configuration updates, please refer to . URL: `{configserverurl}/configfiles/json/{appId}/{clusterName}/{namespaceName}?ip={clientIp}` Method: GET Parameter Description. | Parameter Name | Required | Parameter Value | Remarks | | -- | - | | | | configserverurl | Yes | The address of the Apollo configuration service | | | appId | Yes | The appId of the application | | | clusterName | Yes | clusterName | Normally, just pass in default. If you want to configure by cluster, you can refer to to do the relevant configuration, and then fill in the corresponding cluster name here. | | namespaceName | is the name of the namespace | If no new namespace has been created, just pass in application. If you have created a Namespace and need to use the configuration of that Namespace, pass the corresponding Namespace name. For other types of namespace, you need to pass the namespace name with a suffix, such as datasources.json | ip | | ip | no | ip of the machine where the application will be deployed | This parameter is optional and is used to implement grayscale publishing. If you don't want to pass this parameter, please note that the URL from ? Please note that the entire query parameters starting with the ? sign should not appear in the URL. | The Http interface returns JSON format, UTF-8 encoding, which contains all the configuration items in the corresponding namespace. Return content Sample is as follows. ```json { "portal.elastic.document.type": "biz", "portal.elastic.cluster.name": "hermes-es-fws" } ``` The configuration in the form of properties can be obtained via `{configserverurl}/configfiles/{appId}/{clusterName}/{namespaceName}?ip={clientIp}` Since it is an Http interface, after the URL is assembled OK, it can be accessed directly through a browser, or a relevant http interface testing tool. This interface will get the configuration directly from the database and can be used with configuration push notifications to achieve real-time configuration updates. URL: `{configserverurl}/configs/{appId}/{clusterName}/{namespaceName}?releaseKey={releaseKey}&messages={messages}&label={label}&ip={clientIp}` Method: GET Parameter

| Parameter Name | Required | Parameter Value | Remarks | | -- |-||| | configserverurl | Yes | The address of the Apollo configuration service | | | appId | Yes | The appId of the application | | | clusterName | Yes | clusterName | Normally, just pass in default. If you want to configure by cluster, you can refer to to do the relevant configuration, and then fill in the corresponding cluster name here. | | namespaceName | Yes | is the name of the namespace | If no new namespace has been created, just pass in application. If you have created a Namespace and need to use the configuration of that Namespace, pass the corresponding Namespace name. If the namespace is created and needs to use the configuration of the namespace, pass the namespace name. | | releaseKey | No | Previous releaseKey | The releaseKey of the last release object can be passed to the server to compare the version, if there is no change in the version, the server will return 304 to save traffic and computing. | | messages | No | Latest notificationId | To update the memory cache on the server in real-time, if the `releaseKey` parameter is passed without the `messages` parameter, there is a chance that the latest configuration will not be obtained in a multi-instance server environment with memory caching enabled. The `messages` parameter is a JSON string structure {"details":{"key":notificationId}}. The `appId`, `clusterName`, and `namespaceName` need to be concatenated using the + sign to form the key. Assuming `appId=app`, `clusterName=default`, `namespaceName=test`, and `notificationId=11`, the `messages` parameter would be {"details":{"app+default+test":11}}. When using the messages parameter, URL encoding is required.| | label | No | Labels for grayscale configuration | This parameter is optional and is used for label rule matching in grayscale publishing. | | ip | No | The ip of the machine where the application is deployed | This parameter is optional and is used for ip rule matching in grayscale publishing. | This Http interface returns JSON format, UTF-8 encoding. If the configuration has not changed (the incoming releaseKey and the server-side equal), HttpStatus 304 is returned, and the response body is empty. If the configuration has changed, HttpStatus 200 is returned, and the response body is the meta information of the corresponding namespace and all configuration items in it. The return content Sample is as follows. ```json { "appId": "100004458", "cluster": "default", "namespaceName": "application", "configurations": { "portal.elastic.document.type": "biz", "portal.elastic.cluster.name": "hermes-es-fws" }, "releaseKey": "20170430092936-dee2d58e74515ff3" } ``` Since it is an Http interface, after the URL is assembled OK, it can be accessed directly through a browser, or a relevant http interface testing

Apollo provides push notifications for configuration updates based on Http long polling, and third-party clients can decide whether they need to use this feature depending on their actual needs. If you are not so sensitive to the configuration update time, you can sense the configuration update by refreshing it at regular intervals, the refresh frequency can be determined by the application itself, and it is recommended to be above 30 seconds. If you need to be aware of configuration updates in real time (1 second), you can refer to the following document to implement the configuration update push feature. Here we suggest you to refer to Apollo's Java implementation: , which has more than 200 lines of code and is relatively simple in general. The first thing we need to do is to determine which namespaces need to be configured for update pushing. Apollo's implementation is to register a namespace when the program gets its configuration for the first time, so we know which namespaces need to be configured for update pushing. The result of the initialization is a Map of notifications, the content is namespaceName -> notificationId (initial value of -1). If you find any new namespace that needs to be configured for update pushing during the run, you can directly stuff it into the notification Map. Once you have the notifications Map, you can request services. Here we describe the logic of requesting services, please refer to the interface description later for specific URL parameters and descriptions. request the remote service, bring your application information and notifications information The server checks whether the notificationId is up-to-date for each namespace and corresponding notificationId passed to it. if they are the latest, hold the request for 60 seconds, if there is no configuration change within 60 seconds, then return HttpStatus 304. if there is a configuration change within 60 seconds, then return the latest notificationId of the corresponding namespace, HttpStatus 200. If the notificationId is found to be older than the server, the latest notificationId of the corresponding namespace, HttpStatus 200, will be returned directly. After the client gets the server side return, determine the return HttpStatus . If the returned HttpStatus is 304, that the configuration has not changed, re-execute step 1. If the returned HttpStauts is 200, the configuration has changed, for the change of namespace to pull configuration from the server again, see . Also update the notificationId in the notifications map. re-run step 1. URL: `{configserverurl}/notifications/v2?appId={appId}&cluster={clusterName}&notifications={notifications}` Method: GET Parameter Description. | Parameter Name | Required | Parameter Value | Remarks | | -- | -- | -- | | | configserverurl | Yes | The address of the Apollo configuration service | | | appId | Yes | The appId of the application | | | clusterName | Yes | clusterName | Normally, just pass in

If you want to configure by cluster, you can refer to to do the relevant configuration, and then fill in the corresponding cluster name here. | | notifications | yes | notifications information | pass in the local notifications information, note that here need to be in the form of array to json pass in, such as: [{"namespaceName": "application", "notificationId": 100}, {"namespaceName": "FX.apollo", "notificationId": 200}]. Note that for namespace of properties type, you only need to pass in the namespace name, such as application. for other types of namespace, you need to pass in the namespace name plus the suffix, such as datasources.json | Note 1: Since the server side will hold the request for 60 seconds, please make sure that the timeout for the client to access the server side is greater than 60 seconds. Note 2: Don't forget to for the parameters The Http interface returns a JSON format, UTF-8 encoding, containing the namespace with changes and the latest notificationId. The return content Sample is as follows. ```json [ { "namespaceName": "application", "notificationId": 101 } ] ``` Since it is an Http interface, after the URL is assembled OK, it can be accessed directly through a browser, or a relevant http interface test tool. Apollo has added an access key mechanism since version 1.6.0, so that only authenticated clients can access sensitive configurations. If the application has access keys enabled, the client needs to add a signature when sending a request, otherwise the configuration cannot be accessed. Header information to be set. | Header | Value | Remarks | | - | | | | Authorization | Apollo ${appId}:${signature} | appId: The appId of the application, signature: Generate a signature by combining the access key with the current timestamp in milliseconds, as well as the path and query components of the visited URL. The specific implementation can be found in | | Timestamp | Number of milliseconds elapsed from `1970-1-1 00:00:00 UTC+0` to now | See ) | Under normal circumstances, the Http status code returned by the interface is 200, the following lists the non-200 error code descriptions that Apollo will return. The client needs to check whether the corresponding parameter is correct according to the prompt. The client is not authorized, e.g. the server has configured the access key, but the client is not configured or configured incorrectly. The resource to be accessed by the interface does not exist, usually the URL or the parameters of the URL are wrong, or the corresponding namespace has not yet been published for configuration. The interface access method is incorrect, for example, the interface should use GET to use POST access, etc. The client needs to check whether the interface access method is correct. Other types of errors will return 500 by default. For this type of error, if the application cannot find the cause based on the prompt, you can try to check the server logs to troubleshoot the problem.