Hi @dianalin2 !! Thanks for the PR.!

What about adding some validation to check the query params, as specified in #16 (comment) ? So, if the user specifies other parameters than those specified the endpoint should return a Bad Request explaining what are the expected params.
Another rule we can add here is to limit the count param to be between 1 and 5 (we can change it in the future).

A bonus would be to add a unit test to those scenarios.
What do you say?

@GreenStage @zamariola any thoughts on that?

Hey, @tiagostutz! Thanks for the response, that sounds great.

So, it would return a Bad Request error if there are other parameters, correct? What if the count parameter wasn't between 1 and 5? Would it also return a Bad Request, or would it default to 2?

Hi @GreenStage !
I see your point, but I think validating the input of the request and returning instructional information is a good design practice because it helps the user to have more confidence with the API behavior and what to expect. It is also a good way to teach the user how to use the API because it is a moment where the user is actually attempting to make the requests and is actually coding those requests, not only reading the docs. The 400 return message could even point to the API docs.

About the Google/Facebook example, it doesn't apply to all of their APIs. If you are sending those query params to the URL used in the browser, that's right. Maybe with some API's it may be true either. But there are some Google API's that the scenario is a bit different. Check those Google Classroom API requests:

This request returns 200 with the payload:

curl 'https://content-classroom.googleapis.com/v1/courses?key=AIzaSyAa8yy0GdcGPHdtD083HiGGx_S0vMPScDM' \
  -H 'x-origin: https://explorer.apis.google.com' \
  -H 'authorization: Bearer <YOUR_GOOGLE_KEY>' \
  --compressed

This request with a non-existend query param returns 400 code with a detailed message:

curl 'https://content-classroom.googleapis.com/v1/courses?key=AIzaSyAa8yy0GdcGPHdtD083HiGGx_S0vMPScDM&teacher=S0vMPScDM' \
  -H 'x-origin: https://explorer.apis.google.com' \
  -H 'authorization: Bearer <YOUR_GOOGLE_KEY>' \
  --compressed

Return Message:

{
  "error": {
    "code": 400,
    "message": "Invalid JSON payload received. Unknown name \"teacher\": Cannot bind query parameter. Field 'teacher' could not be found in request message.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "description": "Invalid JSON payload received. Unknown name \"teacher\": Cannot bind query parameter. Field 'teacher' could not be found in request message."
          }
        ]
      }
    ]
  }
}

This other request send an valid parameter teacherId but with an invalid value:

curl 'https://content-classroom.googleapis.com/v1/courses?key=AIzaSyAa8yy0GdcGPHdtD083HiGGx_S0vMPScDM&teacherId=1234' \
  -H 'x-origin: https://explorer.apis.google.com' \
  -H 'authorization: Bearer <YOUR_GOOGLE_KEY>' \
  --compressed

Return Message:

{
  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT"
  }
}

So, even though I think we should follow this approach for a more stable and predictable experience using the API, we could merge this PR here and open another issue to discuss that.!

What do you think @GreenStage and @dianalin2 ?

Cheers @tiagostutz , I fully agree with returning 400 when a valid param has a invalid value.

Regarding,passing an unknow paramater key, the example you provided refers to google's conversion of their grpc API into HTTP, so I am resilient in considering it a good restful example. Note that grpc protocol requires a serialized schema, so it cant afford to have unknown properties in the buffer.

Nevertheless,
Restful is just a name, if you believe parsing all the passed keys in the request and checking if they are known is the right approach for the project, then sure lets go ahead!

The mr is good-to-go by me 👍