|
| 1 | +# How to generate the api clients |
| 2 | + |
| 3 | +First before diving in on the flow of "version control" in terms of the api client a quick start on how to generate them |
| 4 | + |
| 5 | +Essentially you just need to run the `generate-clients` script from the root `package.json` |
| 6 | + |
| 7 | +This will use the configuration from `openapi-ts.config.ts`. This tells **[@hey-api](https://heyapi.dev/openapi-ts/clients)** from where it should get the `schema.json` and where to put the generated clients |
| 8 | + |
| 9 | +If you need a client to a new service, just add a new config object with the `input-output` pair to the array |
| 10 | + |
| 11 | +# Version control with feature flags |
| 12 | + |
| 13 | +If there is a new feature, or you are updating an existing API you might need to update the current client |
| 14 | + |
| 15 | +If the given service's updated API response is backwards compatible you can just run the aforementioned `generate-clients` and you are good to go |
| 16 | + |
| 17 | +## In case of breaking change |
| 18 | + |
| 19 | +In order to be able to release the extension with the changes without the need to wait for the API deployed first we need to have the old and the new version of the client live next to eachother. |
| 20 | + |
| 21 | +In such cases you should modify the already existing `openapi-ts.config.ts` config of the client to generate the old client to a `deprecated` folder: |
| 22 | +e.g.: |
| 23 | + |
| 24 | +```javascript |
| 25 | +import { defineConfig } from '@hey-api/openapi-ts'; |
| 26 | + |
| 27 | +export default defineConfig([ |
| 28 | + // multiple config can go here |
| 29 | + { |
| 30 | + input: 'https://core-balance-api.avax.network/schema.json', |
| 31 | + output: 'packages/service-worker/src/api-clients/deprecated/balance-api', // <-- additional deprecated slug |
| 32 | + }, |
| 33 | + { |
| 34 | + input: 'https://core-profile-api.avax.network/schema.json', |
| 35 | + output: 'packages/service-worker/src/api-clients/profile-api', |
| 36 | + }, |
| 37 | +]); |
| 38 | +``` |
| 39 | + |
| 40 | +After running `generate-clients` you should then update the reference in `packages/service-worker/src/api-clients/clients.ts` to point to the correct folder for the old version |
| 41 | + |
| 42 | +```javascript |
| 43 | +import { createClient as createV1BalanceApiClient } from '~/api-clients/deprecated/balance-api/client'; |
| 44 | +``` |
| 45 | + |
| 46 | +After this you should create the new version of the client by adding the config to the `openapi-ts.config.ts` and running `generate-clients` |
| 47 | + |
| 48 | +```javascript |
| 49 | +import { defineConfig } from '@hey-api/openapi-ts'; |
| 50 | + |
| 51 | +export default defineConfig([ |
| 52 | + // multiple config can go here |
| 53 | + { |
| 54 | + input: 'https://core-balance-api.avax-test.network/schema.json', // <-- pointing to staging |
| 55 | + output: 'packages/service-worker/src/api-clients/balance-api', |
| 56 | + }, |
| 57 | + { |
| 58 | + input: 'https://core-balance-api.avax.network/schema.json', |
| 59 | + output: 'packages/service-worker/src/api-clients/deprecated/balance-api', |
| 60 | + }, |
| 61 | + { |
| 62 | + input: 'https://core-profile-api.avax.network/schema.json', |
| 63 | + output: 'packages/service-worker/src/api-clients/profile-api', |
| 64 | + }, |
| 65 | +]); |
| 66 | +``` |
| 67 | + |
| 68 | +The last step is to add this client to the `packages/service-worker/src/api-clients/clients.ts` file |
| 69 | + |
| 70 | +```javascript |
| 71 | +import { container } from 'tsyringe'; |
| 72 | +import { AppCheckService } from '~/services/appcheck/AppCheckService'; |
| 73 | +import { createClient as createV1ProfileApiClient } from '~/api-clients/profile-api/client'; |
| 74 | +import { createClient as createV1BalanceApiClient } from '~/api-clients/deprecated/balance-api/client'; |
| 75 | +import { createClient as createV2BalanceApiClient } from '~/api-clients/balance-api/client'; |
| 76 | + |
| 77 | +// The rest |
| 78 | + |
| 79 | +const balanceApiClientV2 = createV2BalanceApiClient({ |
| 80 | + baseUrl: process.env.BALANCE_SERVICE_URL, |
| 81 | +}); |
| 82 | +balanceApiClientV2.interceptors.request.use(authInterceptor); |
| 83 | + |
| 84 | +export { |
| 85 | + profileApiClientV1 as profileApiClient, |
| 86 | + balanceApiClientV1 as balanceApiClient, |
| 87 | + balanceApiClientV2, |
| 88 | +}; |
| 89 | +``` |
| 90 | + |
| 91 | +## Usage |
| 92 | + |
| 93 | +In the code than based on feature flags you can either use the old client or the new version of it. |
| 94 | + |
| 95 | +## Cleanup |
| 96 | + |
| 97 | +Once the integration/migration is done you can just update the exports in `packages/service-worker/src/api-clients/clients.ts` and cleanup the logic around feature flags in the code base |
| 98 | + |
| 99 | +```javascript |
| 100 | +import { container } from 'tsyringe'; |
| 101 | +import { AppCheckService } from '~/services/appcheck/AppCheckService'; |
| 102 | +import { createClient as createV1ProfileApiClient } from '~/api-clients/profile-api/client'; |
| 103 | +import { createClient as createV2BalanceApiClient } from '~/api-clients/balance-api/client'; |
| 104 | + |
| 105 | +// The rest |
| 106 | + |
| 107 | +const balanceApiClientV2 = createV2BalanceApiClient({ |
| 108 | + baseUrl: process.env.BALANCE_SERVICE_URL, |
| 109 | +}); |
| 110 | +balanceApiClientV2.interceptors.request.use(authInterceptor); |
| 111 | + |
| 112 | +export { |
| 113 | + profileApiClientV1 as profileApiClient, |
| 114 | + balanceApiClientV2 as balanceApiClient, |
| 115 | +}; |
| 116 | +``` |
0 commit comments