Support
    Home
    Problems
    Contests
    Courses
    Posts
API
Sign in

API

An API, or application programming interface, is the interface through which an application or third-party system can interact with Eolymp. This interface is built on top of the HTTP network protocol. Anyone can write a program and create applications which will receive data or perform certain actions at Eolymp. For example, you could get competition results for processing or analysis, or imports problems to the space's archive.

There are two frameworks you can use to interact with Eolymp:

  • HTTP API (also known as RESTful API) is a basic API which allows performing fine-grained operations, such as creating, updating, deleting or retrieving one particular entry from the database. This API provides a complete set of operations to retrieve or modify everything that exists in Eolymp database. In most of the cases you should use HTTP API.

  • GraphQL API is a read-only API which allows fetching composite data made up of multiple individual entities, for example a list of submissions, together with information about problems and authors (users). This API will be a good fit for fetching data for displaying in user interface or performing data export.

HTTP API

The HTTP API is the base for everything at Eolymp. This API provides granular operations for executing every single process at Eolymp. This API is used by Eolymp internally, by user interfaces and GraphQL API.

Note

This section describes API in a generic way, so it might be a bit technical. We recommend using our SDK, which abstracts networking and provides a handy high-level objects and functions to operate with the API.

The API is split into services, each providing access to certain capability via a collection of methods. For example, eolymp.acl.AclService allows managing Access Control List, this service defines methods used to retrieve, grant and revoke permissions.

Service methods are defined as:

  • HTTP method: GET, POST, PUT, DELETE etc

  • HTTP path, a relative path in the URL

  • Input payload structure (what you send)

  • Output payload structure (what you get in response)

Input and output payloads are always encoded in JSON and sent in the body of the request. Except if the method uses GET, in which case the body is encoded as query parameter q, the value of the parameter is JSON encoded input payload.

Some parameters of the input payload might be present in the URL path, in which case they should not be used in the JSON structure.

The methods define only a relative path (not the entire URL) since they can be used with different base URL. The Base URL defines an object on which the action is performed, for example, you can grant permissions to a space, problem or contest. The API in this case is the same, but the receiving object is different, so you would use a different base URL to specify the context for the API call.

If the call is unbound to any particular object, the base URL should be set to the root URL: https://api.eolymp.com.

In conclusion, to make an API call using the HTTP API you need to find out the base URL and a method you want to call, then compose input payload and send it in the request body (or query for GET requests).

Example

For example, to grant permissions we would use GrantPermission method, which is defined as follows,

  • HTTP method: PUT

  • HTTP path: /acl/{user_id}

  • Input payload includes fields role and entitilements

  • Output payload is empty

Since we want to grant permissions to a space, we will use space URL as base URL: https://api.eolymp.com/spaces/1.

The final request will look like this:

# curl https://api.eolymp.com/spaces/1/acl/24 -X PUT -d '{"role":"ADMIN"}'
{}
Advice

You can choose to manually compose or hard-code the base URL in your application, but we recommend retrieving base URL from the entity itself. For example, if you fetch space, problem or contest you will find url field which contains the base URL for the entity. This would allow us to easily change these URLs in the future without breaking your code.

The easiest way to use the HTTP API is to use one of our SDK (Source Development Kit). These are libraries in different programming languages which implement wire-level details and provide a high-level method to call the API.

GraphQL API

The GraphQL API implements the GraphQL protocol. Under the hood, it still uses the HTTP API described above, but in the case of GraphQL request, individual HTTP API requests are batched together and optimized on the server, so overall performance is much higher.

For example, if you want to receive a list of submissions with problem titles using the HTTP API, you would need to first call ListSubmissions method to get the list of submissions and then LookupStatement method to get information about each problem. This approach will work just fine in many cases, but if performance is important, you might want to use GraphQL to retrieve all information in a single request.

The GraphQL endpoint is available on the space level, at the following address: https://api.eolymp.com/spaces/[space-id]/graphql. You can also retrieve this URL from graphql_url field in the Space structure.

The best way to get yourself familiarized with the GraphQL API is to visit the GraphQL explorer interface. It provides an interactive UI and autocomplete for your queries.

GraphQL explorer

GraphQL explorer is available on a "space" level, so you should place Space ID in the address: https://api.eolymp.com/spaces/[space-id]/explore.

Authentication

Authentication is the process of identifying the user who performs the API call. Authentication consequently affects what resources are available to the requester. If you don't provide any authentication information in the requests, you will only be able publicly available resources.

Authentication information should be specified in Authorization HTTP header in the following format Bearer <secret>, where <secret> refers to the OAuth2 access token or Access key received during authentication.

There are two main authentication mechanisms:

  • OAuth2 access token this protocol is used when you want to perform actions on behalf of some user at Eolymp. For example, let's say you are building an alternative UI for submitting problems, and you would like to create submissions on behalf of a user. In this case, you can implement OAuth2 authentication flow: the user would open your application, get redirected to Eolymp sign in page, sign in and get redirected back to your application with appropriate access_token. Your application will be able to use access_token to perform actions (submitting code) on behalf of the user.

    OAuth2 integration requires some additional configuration on our server, which currently we perform manually. So if you want to use OAuth 2 flow, reach out to us using the contact form, and we will help you set up everything.

  • Access Key is a good fit for personal projects or implementing server to server integrations with Eolymp. Access Key is a special token you can generate at developer.eolymp.com. It has a long expiration time and allows performing actions on behalf of the user who generated it.

Rate limiting

To ensure proper use and operation of the system, there are limits on the number of requests that the user can perform per second. There is a global limit of 6000 req per 5 minutes per IP address as well as fine-grained limits defined for each method separately.

In this article
  • HTTP API
  • GraphQL API
  • Authentication
  • Rate limiting