feat(api-gateway): add common HTTP service errors

[michaelbrewer]

Issue #, if available:

• REST API middleware #1175

Pairs with #507

Description of changes:

Changes:

• Add base ServiceError exception for rest api service errors
• BaseRequestError for 400s
• UnauthorizedError for 401s
• NotFoundError for 404s
• InternalServerError for 500s

Example usage for a unauthorized error

@app.route(method="GET", rule="/unauthorized-error")
def unauthorized_error():
    raise UnauthorizedError("Unauthorized")

will return:

{
	"statusCode": 401,
	"headers": {
		"Content-Type": "application/json"
	},
	"body: "{'statusCode':401,''message':'Unauthorized'}"
}

NOTE: This is related to #507

Checklist

• Meet tenets criteria
• Update tests
• Update docs
• PR title follows conventional commit semantics

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[michaelbrewer]

@heitorlessa I am not sure which of the top service errors to include. So if there are more or less I can update it. Otherwise I can add some docs on usage.

[codecov-commenter]

Codecov Report

Merging #506 (f198ace) into develop (2473480) will increase coverage by 0.00%.
The diff coverage is 100.00%.

@@           Coverage Diff            @@
##           develop     #506   +/-   ##
========================================
  Coverage    99.90%   99.90%           
========================================
  Files          105      107    +2     
  Lines         4238     4266   +28     
  Branches       208      208           
========================================
+ Hits          4234     4262   +28     
  Misses           1        1           
  Partials         3        3           

Impacted Files	Coverage Δ
aws_lambda_powertools/event_handler/__init__.py	100.00% <100.00%> (ø)
aws_lambda_powertools/event_handler/api_gateway.py	100.00% <100.00%> (ø)
...s_lambda_powertools/event_handler/content_types.py	100.00% <100.00%> (ø)
aws_lambda_powertools/event_handler/exceptions.py	100.00% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2473480...f198ace. Read the comment docs.

[heitorlessa]

Looks great! Thanks for adding this one in, Mike! Two minors only - 1/ Moving exceptions to exceptions.py, and 2/ Whether we want to have content_types.py in anticipation that binary mime types will be asked

[heitorlessa]

Fun fact I saw this week which I didn't know is that Python has HTTP Status as a built-in enum. I think the way it's now suffice tbh but thought you'd want to know:

from http import HTTPStatus

HTTPStatus.BAD_REQUEST.value

[heitorlessa]

Explained why exceptions wouldn't be reused in AppSync. Exceptions is the only change pending

[heitorlessa]

To make things easier in terms of import, I'm totally fine with having the localized exceptions.py as well as exported in the API Gateway module itself, for example:

from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, NotFoundError

For those wanting more explicitness, they could:

from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver
from aws_lambda_powertools.event_handler.api_gateway.exceptions import NotFoundError

Alternatively, if you want to keep exceptions within the utility namespace, then we'd need more explicit names to not confuse customers when to use them in AppSync, API Gateway, anotherEventHandler in the future:

from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver
from aws_lambda_powertools.event_handler.exceptions import ApiGatewayNotFoundError

[heitorlessa]

Merging as-is and fixing docstrings to not confuse AppSync customers accidentally using these exceptions meant for API GW/ALB in develop: a519cce

[jplock]

This should be “text/plain”

[heitorlessa]

Thanks for catching it, fixed now in develop w/ a note on mimetypes lib.