Commit e42adc72 authored by Andre Blanke's avatar Andre Blanke
Browse files

Add API.md

parent 46f85054
# URL shortener REST-API
## Overview
| HTTP method | Target URL | Description |
|-------------|-------------|-----------------------------------------------------------------------------------------|
| GET | /index.html | Angular frontend of the URL shortener with an input for a URL that should be shortened. |
| GET | /$id | Redirects the browser to the URL associated with the provided $id. |
| POST | /?url=$url | Endpoint used for the creation of a new id associated with the provided $url. |
## GET /index.html
Retrieves the Angular frontend of the URL shortener located under `/frontend` inside the project structure.
The frontend gives users the ability to input URLs which should be shortened by our service.
Once a button is clicked an HTTP POST request is sent to the `/?url=$url` endpoint and the returning response should be
handled: display an error message if a shortened URL could not be created or display the short URL to the user.
More features such as the following could also be added to `/index.html`:
- A way of not only creating a short URL with a randomly generated `$id` but one with a custom `$id` chosen by the
user.
- Maybe an account system which would allow users to optionally login. A logged in user could see all the URLs that
have been shortened while they were logged in and they might have the ability to remove certain short URLs or
see how often they have been clicked (or even by whom, recording the IP addresses).
- An administrator view that displays a table of all short URLs and their target information, optionally with the same
detail logged in users can see for their short URLs, plus maybe a list of users.
The last two points would require an account system. Login would happen using an email and a password for example.
The frontend should be served directly using the Apache Web Server without a detour over Django.
## GET /$id
Retrieves the unshortened URL associated with the provided `$id` from the database and responds with an HTTP redirect
to it.
This endpoint will be used by clients who have been given a shortened URL and want to visit the original URL behind it.
Because this operation requires a database lookup, Django will be required to serve the `/$id` endpoint.
## POST /?url=$url[&id=$id]
The REST endpoint used for the creation of a new short URL which points to the provided `$url`. If an `$id` was given
and that id is not yet reserved (i.e. can not be found in the database) that custom id is used, otherwise an error is
returned to the user. If `$id` is omitted a unique one will be generated.
Some things will need to be considered when generating new ids or accepting custom ones, such as:
- The id needs to be reachable. If one could create a redirect with an id of `index.html` either our frontend or the
link associated with that id would not be reachable.
- The id should be easy to type, i.e. contain no special characters and not be case-sensitive.
- The ids should most likely not be sequential, as this could be used to find the previous id and thus the URL behind
it. While this service is of course not one used for privacy that should still not be possible.
Care must be taken when specifying `$url`: The provided URL needs to be URL-encoded or should maybe be part of the
payload instead of the URL. If the specified URL were not URL-encoded we would not be able to tell whether
`/?url=https://www.example.com?id=example` is a request to create a short URL to `https://www.example.com` under the
id `example` or to `https://www.example.com?id=example` under a random id, as both would have the same representation.
See [this Stackoverflow answer](https://stackoverflow.com/a/58756335) for an example of how to URL-encode from the
frontenv using `encodeURIComponent`.
This endpoint also needs to be served by Django because, again, database operations are required.
......@@ -4,7 +4,9 @@
├─ ansible/ # Contains Ansible playbooks used by Vagrant
│ ├─ load_balancer.yml
│ └─ worker.yml
├─ frontend/ # Angular frontend, not yet set up
├─ frontend/ # Angular frontend
│ └─ src/
│ └─ index.html
├─ shortener/ # Django backend
│ ├─ shortener/
│ │ ├─ __init__.py
......@@ -13,7 +15,12 @@
│ │ └─ wsgi.py
│ └─ manage.py
├─ ansible.cfg
├─ API.md
├─ README.md
├─ requirements.txt # Required Python packages
└─ Vagrantfile # Virtual machine configurations
```
# API
See [API.md](API.md) for more information on the structure of the API.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment