mirror of
https://github.com/tgstation/tgstation-server.git
synced 2026-08-26 22:48:20 +01:00
50 lines
2.9 KiB
Plaintext
50 lines
2.9 KiB
Plaintext
@page api API
|
|
|
|
@tableofcontents
|
|
|
|
@section api_intro Introduction
|
|
|
|
The TGS4 API is designed to be a fully realized RESTful service. Once hosted, follow the specified protocol for developing new clients or one off requests that provide full control over the server
|
|
|
|
@section api_lib Official Libraries
|
|
|
|
The TGS4 API's canonical definitions are provided as a .NET Standard library in the form of a nuget package located here: https://www.nuget.org/packages/Tgstation.Server.Api
|
|
|
|
An all inclusive TAP interface for using the API is also provided in this package: https://www.nuget.org/packages/Tgstation.Server.Client
|
|
|
|
@section api_header Headers
|
|
|
|
TGS4 expects this set of headers. Failure to provide them may result in
|
|
|
|
- User-Agent: The user agent product header value of the calling program. Should be in the form Agent/Version (i.e. SomeTgsClient/1.2.4)
|
|
- Accept: application/json
|
|
- Api: Another product header value representing the version of the API to use. Currently this must be: Tgstation.Server.Api/4.0.0.0
|
|
|
|
For POST and PUT requests you must also include the content type. Currently only json is supported
|
|
|
|
- Content-Type: application/json
|
|
|
|
For requests made to any Instance based API's a header with the Instance's ID must be provided
|
|
|
|
- Instance: The ID of the instance being accessed
|
|
|
|
An Authentication header is also required. See @ref api_auth
|
|
|
|
@section api_response Response Codes
|
|
|
|
TGS will only every return the response codes listed here
|
|
|
|
- 200: General OK status. Unless the HTTP DELETE verb was used to make the request (In which case the response body will be empty), the response body will contain a json model or array depending on the API called.
|
|
- 400: Bad request made. The response body will contain a @ref apim_error model detailing the error
|
|
- 401: User unauthorized. Invalid or expired credentials were provided. See @ref api_auth for details
|
|
- 404: Not found. A resource was requested that had never existed. In the case of retrieving a resource by ID, it could potentially exist in the future
|
|
- 406: Not acceptable. Consequence of failing to provide an Accept header
|
|
- 408: Request timeout. The client took to long to continue a request
|
|
- 409: Conflict. Documented in the requests that use them
|
|
- 410: Gone. Attempted to access/modify a resource that ideally should have been ready, but isn't or no longer is
|
|
- 419: Rate limited. Used with operations that rely on GitHub.com. If a rate limit is hit for an operation this will be returned
|
|
- 500: Server error. Please report the request and response body to the code repository
|
|
- 501: Not implemented. Currently used in two places: 1. Endpoints that trigger a server restart but the server is not running in a restartable configuration. 2.
|
|
- 503: Service unavailable. The server is either starting up or shutting down and isn't ready to respond to requests. You can try again soon and a response/lack thereof will indicate which of the two events it was
|
|
|