{"openapi":"3.0.0","info":{"version":"v1.0","title":"Students API","description":"This is a very simple API definition to showcase the use of APIs. The goal of the exercise is to execute the operations in the following order:\n* Call POST /token to obtain an authorization token to be used with subsequent calls.\n* Call POST /students to create a student using your name\n* Call GET /students/{studentId} to retrieve the teacher's comment\n\nOnce you have retrieved the teacher's comment, copy-paste the result and send it along with your code via email to georges@berscheid.lu and win a tasty prize!\n"},"tags":[{"name":"Authentication"},{"name":"Students"}],"paths":{"/token":{"post":{"tags":["Authentication"],"summary":"Generate a token from credentials","description":"Takes username and password as input and generates a Bearer token to be used with the Students API","operationId":"createToken","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credentials"}}},"description":"User credentials","required":true},"responses":{"200":{"description":"Provided credentials are valid, a token is returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Token"}}}},"400":{"description":"Credentials aren't valid, e.g. missing username or password","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":400,"description":"Bad request"}}}}}}}}},"/students":{"post":{"tags":["Students"],"summary":"Create a student","description":"Creates a student in the student database. It's enough to provide the first and last name during creation, the ID and teacher comment will be added automatically.","operationId":"createStudent","security":[{"bearerAuthorization":[]}],"parameters":[{"in":"header","name":"Authorization","required":true,"description":"The Bearer token. Use the value obtained from the /token endpoint prefixed by the word 'Bearer '.","schema":{"type":"string","example":"Bearer 9f3N6kT1bv5Jwtq6"}},{"in":"header","name":"X-Student-Agent","required":false,"description":"Identifies the tool used to make the request (e.g., 'postman', 'curl', 'node', 'java'). Used for anonymous usage analytics.","schema":{"type":"string","example":"curl"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Student"},"example":{"firstName":"Jon","lastName":"Snow"}}},"description":"The student to be created. Just provide a first name and a last name","required":true},"responses":{"201":{"description":"The student has successfully been created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Student"}}}},"400":{"description":"Student creation attempt failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":400,"description":"Bad request"}}}}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":401,"description":"Not authorized"}}}}}}}}},"/students/{studentId}":{"get":{"tags":["Students"],"summary":"Get a student","description":"Retrieves the student and the corresponding teacher's comment.","operationId":"getStudent","security":[{"bearerAuthorization":[]}],"parameters":[{"in":"path","name":"studentId","required":true,"schema":{"type":"string"}},{"in":"header","name":"Authorization","description":"The Bearer token. Use the value obtained from the /token endpoint prefixed by the word 'Bearer '.","schema":{"type":"string","example":"Bearer 9f3N6kT1bv5Jwtq6"}}],"responses":{"200":{"description":"The student has been found and is returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Student"}}}},"400":{"description":"Bad request, e.g. studentId missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":400,"description":"Bad request"}}}}}},"401":{"description":"Unauthorized / authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":401,"description":"Unauthorized"}}}}}},"403":{"description":"Forbidden / no access to resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":403,"description":"Forbidden"}}}}}},"404":{"description":"The student with that ID cannot be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"response":{"value":{"code":404,"description":"Not found"}}}}}}}}}},"servers":[{"url":"https://api.berscheid.lu"}],"components":{"securitySchemes":{"bearerAuthorization":{"type":"http","scheme":"bearer"}},"schemas":{"Credentials":{"type":"object","required":["username","password"],"properties":{"username":{"type":"string","minLength":8,"maxLength":20,"example":"jon_snow"},"password":{"type":"string","minLength":8,"maxLength":20,"example":"MyWatchHasEnded"}}},"Error":{"type":"object","required":["code","description"],"properties":{"code":{"type":"integer","minimum":400,"maximum":500},"description":{"type":"string","minLength":0,"maxLength":200}}},"Student":{"type":"object","required":["firstName","lastName"],"properties":{"id":{"type":"string","minLength":16,"maxLength":16,"example":"wEb4t4SbNLXqWhiB"},"firstName":{"type":"string","minLength":2,"maxLength":50,"example":"Jon"},"lastName":{"type":"string","minLength":2,"maxLength":50,"example":"Snow"},"teacherComment":{"type":"string","minLength":10,"maxLength":200,"example":"You know nothing, Jon Snow"}}},"Token":{"type":"object","required":["token"],"properties":{"token":{"type":"string","minLength":16,"maxLength":16,"example":"wEb4t4SbNLXqWhiB"}}}}}}