This API provides access to the list of sports that the University offer, with theirs correspondent schedules.
- RESTful URLs
- HTTP Verbs
- Responses
- Error handling
- Security
- Response's body size limits
- Endpoints List
- Use plural nouns always (no singular nouns).
- Use HTTP verbs (GET, POST, DELETE) to operate on the collections and elements.
- You can´t go deeper than resource/identifier/resource.
- HTTP headers: our API will ignore any aditional header in the requests. It will make use of them in the responses
- List of sports:
- A single sport:
- List of schedules for a sport:
- Delete a sport:
- Non-plural noun:
- An unrecognized path:
HTTP verbs, or methods, are used in compliance with their definitions under the HTTP/1.1 standard.
The action taken will be contextual to the type being worked on and its current state. Here's an example of how HTTP verbs map to create, read and delete operations in a particular context:
| HTTP METHOD | POST | GET | DELETE |
|---|---|---|---|
| CRUD OP | CREATE | READ | DELETE |
| /sports | Create new sport | List sports | Error |
| /sports/name | Error | show sport name | Delete name |
Responses uses HTTP status codes to indicate they type. Bodies -if presents- are always in Json format We Use five simple, common response codes (besides the ones for authentication):
- 404 - the resource can't be found
- 200 - OK
- 201 - Resource created (for POST only)
- 400 - Bad Request
- 500 - Internal Server Error
Error responses include an error HTTP status code and optionaly a message into their body as a string
from the previous responses codes, the ones for errors are
- 404 - the resource can't be found
- 400 - Bad Request
- 500 - Internal Server Error
To protect the sended data between server and client we use SSL certificates. This was implemented using the keytool from de JDK to access the keys.keystore file containing the certificates
For actions that modify the information in the server will require authorization. This are the ones related to POST and DELETE HTTP verbs. For them, we use an implementation of Apache Shiro to authenticate and authorise users based on an username-password pair. When an unauthenticated user tries to make a POST request, the api will retrieve a 401 response with the header WWW-Authenticate set. This prompts the browser to show a log-in dialogue and prompt the user to enter their username and password. The request is made to the resource again, this time with the Authorization header set, containing the username and password encoded in Base64. When we receive this information, we check the username and password to authenticate the user and check if it is authorised to do such acction. If this is successful then the routing of the request is allowed to continue, otherwise a 403 response is returned to signify that access is denied.
To remain the authentication and authorization alive between requests, we use cookies to save the session of the current user
The only endpoints which could return an arbitrary long response are
in the context of our problem, neither of them will never return a large amount of data.
- For the list of sports, it could never be larger than the number of sports that can be planned in a single multi-sport space over a week
- For the list of schedules, it could never be larger than the number schedules that a sport can has over a week
for this reasons we decide to not implement paging at this version of the api
the format of this list is
-
-
- explination
- explination
-
- explination
- explination
-
Any combination of the nexts urls and HTTP Verbs that are not listed are forbidden and will returns an 404 error
-
-
- Returns an HTTP Response with status code 200 and the requested sport parsed as Json into its body
- Returns an HTTP Response with status code 500 and the exception's details into its body
-
-
-
- Returns an HTTP Response with status code 200 and a list of all the sports parsed as Json into its body
- Returns an HTTP Response with status code 500 and the exception's details into its body
- Returns an HTTP Response with status code 404
-
- Returns an HTTP Response with status code 201, and a header "LOCATION" indicating the url for the new sport
- Returns an HTTP Response with status code 500 and the exception's details into its body
- Returns an HTTP Response with status code 400 and a "duplicated sport" message into its body
- Returns an HTTP Response with status code 400 and a "duplicated sport" message into its body
- Returns an HTTP Response with status code 400
-
- Returns an HTTP Response with status code 200
- Returns an HTTP Response with status code 500 and the exception's details into its body
- Returns an HTTP Response with status code 404
-
-
-
- Returns an HTTP Response with status code 200 and the requested sport's schedules parsed as Json into its body
- Returns an HTTP Response with status code 500 and the exception details into its body
-
- Returns an HTTP Response with status code 201
- Returns an HTTP Response with status code 500 and the exception's details into its body
- Returns an HTTP Response with status code 400 and a "the specified schedule is already registered or the specified sport is not registered" message into its body
- Returns an HTTP Response with status code 400
-
- Returns an HTTP Response with status code 200
- Returns an HTTP Response with status code 500 and the exception's details into its body
- Returns an HTTP Response with status code 404
- Returns an HTTP Response with status code 400
-