C Sharp

C Sharp - API topic - Parameter tags

Check out this method:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
/// <summary>
/// Retrieves a representative by CompanyID and ID
/// </summary>
/// <param name="companyID">Company unique identifier</param>
/// <param name="id">Representative unique identifier</param>
/// <returns>Representative details</returns>
/// <response code="200">Representative found</response>
/// <response code="404">Representative not found</response>
[HttpGet("GetOne/{id}")]
[ProducesResponseType(typeof(ApiResponse<RepresentativeGet>), 200)]
[ProducesResponseType(404)]
[SwaggerOperation(Summary = "Get representative by ID", Description = "Returns a single representative by its CompanyID and unique identifier")]
public async Task<IActionResult> G1etOneAsync([FromQuery] Guid companyID, long id)
{
    var result = await _service.GetByIdAsync(companyID, id);
    if (result == null)
        return NotFound(new ApiResponse<RepresentativeGet>
        {
            Success = false,
            Errors = new List<ApiError>
            {
                new ApiError
                {
                    Code = "NOT_FOUND",
                    Message = $"Representative with CompanyID {companyID} and ID {id} not found"
                }
            },
            Metadata = new ApiMetadata
            {
                RequestId = HttpContext.TraceIdentifier
            }
        });
    
    return Ok(new ApiResponse<RepresentativeGet>
    {
        Success = true,
        Data = result,
        Metadata = new ApiMetadata
        {
            RequestId = HttpContext.TraceIdentifier
        }
    });
}

In particular this method signature.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
/// <summary>
/// Retrieves a representative by CompanyID and ID
/// </summary>
/// <param name="companyID">Company unique identifier</param>
/// <param name="id">Representative unique identifier</param>
/// <returns>Representative details</returns>
/// <response code="200">Representative found</response>
/// <response code="404">Representative not found</response>
[HttpGet("GetOne/{id}")]
[ProducesResponseType(typeof(ApiResponse<RepresentativeGet>), 200)]
[ProducesResponseType(404)]
[SwaggerOperation(Summary = "Get representative by ID", Description = "Returns a single representative by its CompanyID and unique identifier")]
public async Task<IActionResult> G1etOneAsync([FromQuery] Guid companyID, long id)
{
}

Notice 2 parameters

  • [FromQuery] Guid companyID
  • Long id

The [FromQuery] is a tag which tells the method to get the company ID as a parameter being passed in.

Here is an AI explanation

The companyID parameter is marked [FromQuery], so it appears as a query string parameter, not in the route path.

Looking at the Representative controller:

1
[HttpGet("GetOne/{id}")]public async Task<IActionResult> GetOneAsync([FromQuery] Guid companyID, long id)
  • {id} is a route parameter (in the path), so it appears in the URL: /api/v1/Representative/GetOne/{id}
  • companyID is [FromQuery], so it appears as a query parameter: ?companyID=…

Here is a curl example

1
2
3
curl -X 'GET' \
  'https://localhost:5001/api/v1/Representative/GetOne/1?companyID=e94ca8e6-c70c-4787-825a-674701e42728' \
  -H 'accept: text/plain'