Open Hackathon Rest API V2
Rest API Overview
A swagger 2.0 compliant Rest API server for open hackathon.
Authentication
Some APIs allow anonymous access, some others require a valid
token
. Open hackathon
platform has integrated with
Authing. Any web app which onboarded to Authing
is able to get a valid token. A typical flow:
-
In you web app, follow Authing documents to login user. Can use any Authing-supported login method including password-based and social login(github, WeChat and so on).
All login-related configs are configured in Authing or social login provider like github.
- After a successful login, post the response data(token is included) returend by Authing to api
/v2/login
. This step MIGHT be skipped in future.
-
Afterwards, you can call other APIs with an
Authorization
header. The header value is of format token TOKENVALUE
.
Notice that if the token expires, users need to login again to get a new token.
Headers["Authorization"]="token TOKENVALUE"
Authorization
User is identified using the access
token
. Access is determined based on the user/token. Quick
tips about access:
-
View the API Spec, if the summary of
an API contains (Auth) or (Auth Policies:xxx),
Authorization
header is required.
Otherwise, the API can be called anonymously.
- If Policies is empty, it means any login user is allowed to access the API.
-
If Policies is NOT empty, it means only users who have proper access can access the API.
The policy name is quite descriptive. e.g. PlatformAdministrator means only admins of the hackathon platform are allowed, so only several selected accounts are allowd.
Another typical example, HackathonAdminitrator, only admins of a hackathon are allowed.
Multilingual Support
Multiple languages support is still in progress. We are aiming to support 2 languanges: English(
default) and Chinese. Scopes:
-
Web Pages: Not supported. This includes the home page, Swagger UI etc.
-
User Input: Not supported. Any content from users is not supported. e.g. the display name and content of a hackathon.
-
Server-generated Content: Partially Supported. Contents generated by server are partially supported. Still working in progress to support.
Eventually all server-generated content will be supported, including the message in error response, activity logs etc.
-
Content from partners: Not supported. For instance, user info from Github/Authing cannot be localized.
To get response in a different language, add Http Header
Accept-Language
to your request:
Headers["Accept-Language"]="zh-CN"
Error Response
Http response with a code >= 400 is considered Error. A
RFC7807-compliant standard
response body is retured. The response is of type
ProblemDetails(code other than 400)
or
ValidationProblemDetails(http code 400). Example:
{
"type": "https://httpstatuses.com/400",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "|790eea2d-4a0d4972a27712a5.",
"errors": {
"maxEnrollment": [
"The field maxEnrollment must be between 1 and 100_000."
]
}
}