[FLAG-1239]: Add GADM Query Parameter When GETing Areas

[willian-viana]

Overview

This card makes the GADM version explicit when a user’s Area is being requested from the Resource Watch (RW) Area microservice.

Making a distinction between different versions of administrative boundary IDs is critical to quickly adopting future boundary updates.

Currently, administrative Areas are referenced with GADM IDs. These are used when saving/loading Areas in Flagship. They’re also used in URL paths within Flagship for dashboards, embeds, and the like. Unfortunately, there is no guarantee from the GADM organization that IDs remain consistent across GADM versions.

For a made-up example, the same subregion in Mexico (or any other country) can have two sets of IDs depending on what GADM version is referenced:
GADM 3.6: MEX 8 14
GADM 4.1: MEX 9 12

This drastically affects Flagship's ability to keep a user’s areas consistent when changing to an updated GADM version.

Scope

This involves only adding two query parameters to a RW Area GET request.

Currently, requests for a user’s Areas look like this in Flagship: GET /v2/area

The updated implementation will add two query parameters: GET /v2/area?source[provider]=gadm&source[version]=3.6

Implementation Details

The RW Area microservice will ignore these parameters until later in the RW Area microservice GADM Epic.

However, the benefit is to get started on implementing the necessary interface updates and verifying integration with a low-risk approach.

It’s totally acceptable to hard-code these values to gadm and 3.6. Future cards will then make these values dynamic (to support 4.1).

Any other query parameters being sent for similar requests will still need to be sent. This is an addition only (in order to preserve backward compatibility).

Resources

Miro sticky with comments

[gtempus]

Looking good, @willian-viana.
Let's just focus on the GET requests for this PR.

[gtempus]

You don't have to send application=gfw as part of this PR.
I don't think it'll hurt anything. I just wanted to make sure y'all know it's not required.

It looks like Flagship doesn't send it now, so maybe you shouldn't send it in this PR.

[gtempus]

These are PATCH and POST URLs. They don't need to have the new query params.
For these, a change in the body will be needed but, it's not part of the scope of this card.

[willian-viana]

I just realized I replicated the source for all methods instead of GET only haha thank you for notice it!

[gtempus]

Delete doesn't need the params, either.

[gtempus]

Your changes are what I was thinking, @willian-viana. 💯

Where are the tests? I do see that y'all have a few services tested.

Just as a warm-up, I added a basic areas.spec.js test for you to consider:

services/__tests__/areas.spec.js

import { getArea } from '../areas';
import { apiAuthRequest } from "../../utils/request";

jest.mock('../../utils/request', () => ({
  apiAuthRequest: {
    get: jest.fn(),
  },
}));

describe('Areas Service', () => {
  describe('Getting a Single Area', () => {
    describe('The Request to the API', () => {
      it('should add source params for gadm 4.1', async () => {
        // arrange
        apiAuthRequest.get.mockResolvedValueOnce({data: {data: {attributes: {}}}});
        
        // act
        await getArea('abcdef123456789');

        // assert
        expect(apiAuthRequest.get).toHaveBeenCalledWith(
          '/v2/area/abcdef123456789?source[provider]=gadm&source[version]=4.1',
          {
            headers: {}
          }
        )
      });
    });
  });
});

Maybe add another for getAll? 😄