There are many types of tests, and they all seem great in theory, but how do we test a REST API? In order to do that, let\u2019s first break down a REST API into parts, so we can focus on testing one part at a time.<\/p>\n\n\n\n
A REST API is an interface that accepts connections via the internet, executes some business logic, and then returns a result. Fundamentally, that means that an API has input, business logic, and output. The business logic should be tested using traditional unit test techniques<\/a>. After that, what\u2019s left is testing the input and output.<\/p>\n\n\n\n APIs over HTTP (an internet protocol), called HTTP APIs\u2019 have input and output which both have metadata (data about the requests) called headers<\/em> that are used to give certain information, like how to interpret the data sent (is it encrypted? Is it text? Is it JSON? etcetera).\u00a0<\/p>\n\n\n\n HTTP API output also has a special piece of metadata called the status code, which is an integer, meant to be machine readable, not human readable, which is used to give an overall status of the request.<\/p>\n\n\n\n The next step that you see in most (but not all!) APIs, is some way of controlling what the user can and cannot do. You could call it user validation or permissions, but it\u2019s usually just called authorization and authentication.<\/p>\n\n\n\n In order to break down how to actually test these pieces, let’s start off with an example Python Flask API that we’ll be testing against:<\/p>\n\n\n In an HTTP API, you\u2019re always going to have one, and they can have a lot of value, as they offer a programmatic quick summary of the status of a request. However, remember that the developers behind each API determine what HTTP codes they send back, so sometimes a misleading or incorrect HTTP status code can be sent back. That\u2019s good to keep in mind just because a common mistake is assuming that the OK<\/strong> status means everything went well.<\/p>\n\n\n\n An example of this, is that in many asynchronous processes over APIs, the OK<\/strong> status received from an API may just mean it received the request successfully, not that the API actually did anything with that data. The process could fail later down the line, and the HTTP status code won\u2019t magically change to reflect that.<\/p>\n\n\n\n The first thing to know about HTTP status codes is that they are intended to be read by machines, so they\u2019re really just numbers like 200, even though those numbers map to human readable values, like OK.<\/p>\n\n\n\n The really important thing to know about HTTP codes is that the range of 200<\/strong>–299<\/strong> means everything went well, 300<\/strong>–399<\/strong> means some kind of redirect occurred, 400<\/strong>–499<\/strong> means some kind of understandable error occurred, and 500<\/strong>+ means something, most likely catastrophic, happened. Personally, I love to reference HTTP Cats<\/a> for what each code means, but there is also an official spec you can read<\/a>.<\/p>\n\n\n\n So, how do we test for these status codes? <\/p>\n\n\n\n Let’s first think about what kinds of tests you can build for a program. There are:<\/p>\n\n\n\n Let’s apply these different paths to our API status code testing. Let’s test that:<\/p>\n\n\n\n It’s worth mentioning that 500 errors are inherently errors that aren\u2019t expected or handled, so if you can come up with a test case for a 500+ error then the error itself should probably be a 400-499 error instead.<\/p>\n\n\n The next piece of an API request to focus on is the headers of your HTTP calls. Headers contain all types of metadata about the request itself. For example, a common header is the \u2139\ufe0f A very important note about headers is that many of them are very easy to change, so if you have your API be dependant on them for things like permissions you could be leaving your API open to man in the middle attacks.<\/p>\n<\/blockquote>\n\n\n\n Now that we have tests for our REST API\u2019s status codes and headers, we want to test that a user can only do what we expect them to be able to do.<\/p>\n\n\n\n In the industry you\u2019ll sometimes hear people say things about \u201cauth\u201d-ing or \u201cauth\u201ded, but what does that mean? It is jargon for saying both authenticated and authorized. But what is the difference?<\/p>\n\n\n\n This boils down to two questions: Are you who you say you are, and are you allowed to perform the action you\u2019re trying to do. In other words \u2013 are you really my housemate, and even if you are, are you really allowed in my room? These two questions are the core of authentication and authorization. In the vernacular they\u2019re often used interchangeably, but they actually have separate meanings.<\/p>\n\n\n\n Authentication is checking if you are who you say you are. In other words, when you log in to a website and you give it your username and password you are authenticating<\/em> – saying you are a real user. Authentication is who you are<\/em>.<\/p>\n\n\nfrom<\/span> flask import<\/span> Flask, jsonify, request, views\n\napp = Flask(__name__)\n\n\nclass<\/span> CustomFlaskAPI<\/span>(views.MethodView)<\/span>:<\/span>\n def<\/span> get<\/span>(self)<\/span>:<\/span>\n headers = request.headers\n if<\/span> headers.get(\"should_error\"<\/span>, False<\/span>):\n return<\/span> jsonify({\"error\"<\/span>: \"ERROR\"<\/span>}), 400<\/span>\n\n return<\/span> jsonify({\"a\"<\/span>: \"b\"<\/span>}), 200<\/span>\n\n def<\/span> post<\/span>(self)<\/span>:<\/span>\n content_type = request.headers.get(\"Content-Type\"<\/span>)\n if<\/span> content_type != \"application\/json\"<\/span>:\n return<\/span> jsonify({\n \"error\"<\/span>: \"Unknown Content Type: {}\"<\/span>.format(content_type)\n }), 415<\/span>\n return<\/span> jsonify({}), 200<\/span>\n\n\n# Add Endpoints:<\/span>\napp.add_url_rule('\/api\/'<\/span>, view_func=CustomFlaskAPI.as_view('api'<\/span>))\n\n\nif<\/span> __name__ == \"__main__\"<\/span>:\n app.run()<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\nHTTP status codes are important<\/h3>\n\n\n\n
\n
\n
import<\/span> unittest\nfrom<\/span> unittest import<\/span> TestCase\nimport<\/span> requests # pip install requests<\/span>\n\n\nclass<\/span> IntegrationTests<\/span>(TestCase)<\/span>:<\/span>\n def<\/span> test_status_codes_200<\/span>(self)<\/span>:<\/span>\n result = requests.get(\"http:\/\/localhost:5000\/api\/\"<\/span>)\n assert<\/span> result.status_code == 200<\/span>\n\n def<\/span> test_status_codes_400<\/span>(self)<\/span>:<\/span>\n result = requests.get(\n \"http:\/\/localhost:5000\/api\/\"<\/span>,\n headers={\"should_error\"<\/span>: \"error\"<\/span>},\n )\n assert<\/span> result.status_code == 400<\/span>\n\n def<\/span> test_status_codes_404<\/span>(self)<\/span>:<\/span>\n result = requests.get(\"http:\/\/localhost:5000\/does_not_exist\/\"<\/span>)\n assert<\/span> result.status_code == 404<\/span>\n\n\nif<\/span> __name__ == \"__main__\"<\/span>:\n unittest.main()\n<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\nHeaders are the metadata of requests<\/h3>\n\n\n\n
content-type<\/code> which tells the requester what format the data is in (for example application\/json<\/code> means it\u2019s in JSON). There are some standard headers, but custom ones can also be added so all of the above should be tested.<\/p>\n\n\nimport<\/span> unittest\nfrom<\/span> unittest import<\/span> TestCase\nimport<\/span> requests\n\n\nclass<\/span> IntegrationTests<\/span>(TestCase)<\/span>:<\/span>\n def<\/span> test_header_invalid<\/span>(self)<\/span>:<\/span>\n result = requests.post(\n \"http:\/\/localhost:5000\/api\/\"<\/span>,\n headers = {'Content-Type'<\/span>: 'random\/content'<\/span>},\n json = {\n \"username\"<\/span>: \"fake\"<\/span>,\n \"password\"<\/span>: \"fakse\"<\/span>,\n },\n )\n assert<\/span> result.status_code == 415<\/span>\n assert<\/span> result.headers.get(\"Content-Type\"<\/span>) == \"application\/json\"<\/span>\n\n def<\/span> test_header_correct<\/span>(self)<\/span>:<\/span>\n result = requests.post(\n \"http:\/\/localhost:5000\/api\/\"<\/span>,\n headers = {'Content-Type'<\/span>: 'application\/json'<\/span>},\n json = {\n \"username\"<\/span>: \"fake\"<\/span>,\n \"password\"<\/span>: \"fakse\"<\/span>,\n },\n )\n assert<\/span> result.status_code != 415<\/span>\n assert<\/span> result.headers.get(\"Content-Type\"<\/span>) == \"application\/json\"<\/span>\n\n\nif<\/span> __name__ == \"__main__\"<\/span>:\n unittest.main()<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n\n
Authentication versus Authorization<\/h3>\n\n\n\n
Authentication<\/h4>\n\n\n\n
import<\/span> unittest\nfrom<\/span> unittest import<\/span> TestCase\nimport<\/span> requests\nimport<\/span> sqlalchemy\nfrom<\/span> sqlalchemy.orm import<\/span> sessionmaker\nfrom<\/span> flask import<\/span> Flask, jsonify, request, views\n\napp = Flask(__name__)\n\n# Connect to the DB and reflect metadata.<\/span>\nengine = sqlalchemy.create_engine(\"postgresql:\/\/coderpad:@\/coderpad?host=\/tmp\/postgresql\/socket\"<\/span>)\nconnection = engine.connect()\nSession = sessionmaker(bind=engine)\nsession = Session()\nmetadata = sqlalchemy.MetaData()\nmetadata.reflect(bind=engine)\n\n\nclass<\/span> CustomFlaskAPI<\/span>(views.MethodView)<\/span>:<\/span>\n def<\/span> post<\/span>(self)<\/span>:<\/span>\n content_type = request.headers.get(\"Content-Type\"<\/span>)\n if<\/span> content_type != \"application\/json\"<\/span>:\n return<\/span> jsonify({\n \"error\"<\/span>: \"Unknown Content Type: {}\"<\/span>.format(content_type)\n }), 415<\/span>\n\n username = request.json.get('username'<\/span>)\n password = request.json.get('password'<\/span>) # NEVER PASS THIS IN PLAIN TEXT<\/span>\n\n if<\/span> username is<\/span> None<\/span> or<\/span> password is<\/span> None<\/span>:\n return<\/span> jsonify({\n \"error\"<\/span>: \"Missing username or password\"<\/span>,\n }), 400<\/span>\n\n users_table = metadata.tables[\"users\"<\/span>]\n result = connection.execute(\n users_table.select().where(\n (users_table.c.username == username)\n & (users_table.c.password == password) # Never actually store in plain text<\/span>\n )\n ).fetchall()\n\n if<\/span> (len(result) <= 0<\/span>):\n return<\/span> jsonify({\n \"error\"<\/span>: \"Invalid username or password\"<\/span>,\n }), 400<\/span>\n\n return<\/span> jsonify({}), 200<\/span>\n\n\n# Add Endpoints:<\/span>\napp.add_url_rule('\/api\/'<\/span>, view_func=CustomFlaskAPI.as_view('api'<\/span>))\n\n\nclass<\/span> IntegrationTests<\/span>(TestCase)<\/span>:<\/span>\n def<\/span> test_login<\/span>(self)<\/span>:<\/span>\n result = requests.post(\n \"http:\/\/localhost:5000\/api\/\"<\/span>,\n headers = {'Content-Type'<\/span>: 'application\/json'<\/span>},\n json = {\n \"username\"<\/span>: \"real_user\"<\/span>,\n \"password\"<\/span>: \"real_encrypted_password\"<\/span>,\n },\n )\n assert<\/span> result.status_code == 200<\/span>\n\n def<\/span> test_invalid_login<\/span>(self)<\/span>:<\/span>\n result = requests.post(\n \"http:\/\/localhost:5000\/api\/\"<\/span>,\n headers = {'Content-Type'<\/span>: 'application\/json'<\/span>},\n json = {\n \"username\"<\/span>: \"fake_user\"<\/span>,\n \"password\"<\/span>: \"fake_encrypted_password\"<\/span>,\n },\n )\n assert<\/span> result.status_code ==