From 56213935f420567ac864db1c5c03e444ad2d3eaf Mon Sep 17 00:00:00 2001 From: John Buck Date: Sun, 23 Apr 2023 20:28:27 -0400 Subject: [PATCH 1/3] Add provider object to api endpoint The optional provider object gives detailed information about the application serving up the endpoints. Move name and logo properties into new provider object. --- Contest_API.md | 49 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 37 insertions(+), 12 deletions(-) diff --git a/Contest_API.md b/Contest_API.md index 3ba58cdf..8d4daf47 100644 --- a/Contest_API.md +++ b/Contest_API.md @@ -600,7 +600,7 @@ array of ID, does not have to be supported. ### API information -Provides information about the API. +Provides information about the API and the data provider. The following endpoint is associated with API information: @@ -610,13 +610,32 @@ The following endpoint is associated with API information: Properties of version object: +| Name | Type | Description +| :----------- | :---------------- | :---------- +| version | string | Version of the API. For this version must be the string `draft`. Will be of the form `-`, `--draft`, or simply `draft`. +| version\_url | string | Link to documentation for this version of the API. +| provider | provider object ? | Information about the data provider + +Properties of the provider object: + | Name | Type | Description | :----------- | :-------------- | :---------- -| version | string | Version of the API. For this version must be the string `draft`. Will be of the form `-`, `--draft`, or simply `draft`. -| version\_url | string | Link to documentation for this version of the API. | name | string ? | Name of this data provider. +| version | string ? | Provider's application version string +| build\_date | TIME ? | TIME provider's application was built +| type | string ? | See Known Provider Types table below +| doc\_url | string ? | Link to provider's documentation | logo | array of FILE ? | Logo for this data provider, intended to be an image with aspect ratio near 1:1. Only allowed mime types are image/\*. The different files in the array should be different file formats and/or sizes of the same image. +#### Known Provider Types + +The list below contains allowed provider types. + +| Type | Description +| :---- | :---------- +| CCS | Contest Control System +| CDS | Contest Data Server + #### Examples Request: @@ -629,15 +648,21 @@ Returned data: { "version": "draft", "version_url": "https://ccs-specs.icpc.io/draft/contest_api", - "name": "Kattis", - "logo": [{ - "href": "/api/logo", - "hash": "36dcf7975b179447783cdfc857ce9ae0", - "filename": "logo.png", - "mime": "image/png", - "width": 600, - "height": 600 - }] + "provider" : { + "name": "DOMjudge", + "version" : "8.3.0DEV/4ac31de71", + "build_date" : "2023-04-20T10:00:00+01" + "type" : "CCS", + "doc_url" : "https://www.domjudge.org/demoweb/api/doc", + "logo": [{ + "href": "/api/logo", + "hash": "36dcf7975b179447783cdfc857ce9ae0", + "filename": "logo.png", + "mime": "image/png", + "width": 600, + "height": 600 + }] + } } ``` From af6d164087b6a80f55328749381afdeef8f37086 Mon Sep 17 00:00:00 2001 From: John Buck Date: Mon, 24 Apr 2023 15:10:02 -0400 Subject: [PATCH 2/3] Changes requested from PR Make name property of provider required if provider is present. Remove provider type property as superfluous. Change description of provider build date to Timestamp instead of TIME. --- Contest_API.md | 15 ++------------- 1 file changed, 2 insertions(+), 13 deletions(-) diff --git a/Contest_API.md b/Contest_API.md index 8d4daf47..336c39d7 100644 --- a/Contest_API.md +++ b/Contest_API.md @@ -620,22 +620,12 @@ Properties of the provider object: | Name | Type | Description | :----------- | :-------------- | :---------- -| name | string ? | Name of this data provider. +| name | string | Name of this data provider. | version | string ? | Provider's application version string -| build\_date | TIME ? | TIME provider's application was built -| type | string ? | See Known Provider Types table below +| build\_date | TIME ? | Timestamp when the provider's application was built | doc\_url | string ? | Link to provider's documentation | logo | array of FILE ? | Logo for this data provider, intended to be an image with aspect ratio near 1:1. Only allowed mime types are image/\*. The different files in the array should be different file formats and/or sizes of the same image. -#### Known Provider Types - -The list below contains allowed provider types. - -| Type | Description -| :---- | :---------- -| CCS | Contest Control System -| CDS | Contest Data Server - #### Examples Request: @@ -652,7 +642,6 @@ Returned data: "name": "DOMjudge", "version" : "8.3.0DEV/4ac31de71", "build_date" : "2023-04-20T10:00:00+01" - "type" : "CCS", "doc_url" : "https://www.domjudge.org/demoweb/api/doc", "logo": [{ "href": "/api/logo", From 39b3b02cb7e097115f45c1533248170612d3f6e8 Mon Sep 17 00:00:00 2001 From: John Buck Date: Mon, 15 May 2023 15:06:22 -0400 Subject: [PATCH 3/3] Remove doc_url and build_date It was suggested that build_date can be part of the provider version string. It was agreed that having any URL in the provider object is unnecessary; knowing the provider should be enough information to track down any documentation you may need. --- Contest_API.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/Contest_API.md b/Contest_API.md index 336c39d7..827fc4b7 100644 --- a/Contest_API.md +++ b/Contest_API.md @@ -622,8 +622,6 @@ Properties of the provider object: | :----------- | :-------------- | :---------- | name | string | Name of this data provider. | version | string ? | Provider's application version string -| build\_date | TIME ? | Timestamp when the provider's application was built -| doc\_url | string ? | Link to provider's documentation | logo | array of FILE ? | Logo for this data provider, intended to be an image with aspect ratio near 1:1. Only allowed mime types are image/\*. The different files in the array should be different file formats and/or sizes of the same image. #### Examples @@ -641,8 +639,6 @@ Returned data: "provider" : { "name": "DOMjudge", "version" : "8.3.0DEV/4ac31de71", - "build_date" : "2023-04-20T10:00:00+01" - "doc_url" : "https://www.domjudge.org/demoweb/api/doc", "logo": [{ "href": "/api/logo", "hash": "36dcf7975b179447783cdfc857ce9ae0",