From 4c42c177e88ae01cd41af4074a65eb45c7a7f415 Mon Sep 17 00:00:00 2001 From: ProofOfKeags Date: Mon, 20 May 2024 13:03:12 -0600 Subject: [PATCH] adds package protocol documentation (#112) * adds package protocol documentation * Update marketplace_protocol.md * Update marketplace_protocol.md * Update marketplace_protocol.md * Update marketplace_protocol.md Co-authored-by: Aiden McClelland <3732071+dr-bonez@users.noreply.github.com> * Update marketplace_protocol.md Co-authored-by: Aiden McClelland <3732071+dr-bonez@users.noreply.github.com> * Update marketplace_protocol.md Co-authored-by: Aiden McClelland <3732071+dr-bonez@users.noreply.github.com> * Update marketplace_protocol.md Co-authored-by: Aiden McClelland <3732071+dr-bonez@users.noreply.github.com> * Update marketplace_protocol.md Co-authored-by: Aiden McClelland <3732071+dr-bonez@users.noreply.github.com> * Update marketplace_protocol.md Co-authored-by: Aiden McClelland <3732071+dr-bonez@users.noreply.github.com> --------- Co-authored-by: Lucy <12953208+elvece@users.noreply.github.com> Co-authored-by: Aiden McClelland <3732071+dr-bonez@users.noreply.github.com> --- marketplace_protocol.md | 242 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 marketplace_protocol.md diff --git a/marketplace_protocol.md b/marketplace_protocol.md new file mode 100644 index 0000000..468c893 --- /dev/null +++ b/marketplace_protocol.md @@ -0,0 +1,242 @@ +# Marketplace Protocool Documentation + +## Terms + +- PkgId: string comprised of lowercase letters, numbers and -'s, must begin with letter, must not end with -, ex: ride-the-lightning +- S9PK: ".s9pk" +- Emver: string that matches the following regex: \d((\.\d){2})((\d\.)?) +- EmverMod: ">" OR "<" OR "=" OR ">=" OR "<=" OR "!=" +- EmverRange: OR "\*" OR "!" + +## Routes + +### GET /info + +#### Query Params + +NONE + +#### Returns + +```json +{ + // this is the name of the marketplace and will show in the marketplace view on EOS + "name": "", + "categories": [""] +} +``` + +#### Requirements + +- categories must be lowercase. +- all category tags that appear in /index MUST appear here + +### GET /index + +#### Query Params + +- (Required) "eos-version-compat": EmverRange specifying what versions of the OS that pack the packages are valid response items +- (Optional) "ids": json array of package ids +- (Optional) "category": string representing +- (Optional) "page": which page of the index you want (NOTE: starts at 1) (Default: 1) +- (Optional) "per-page": size of the page you want (Default: 20) + +#### Returns + +```json +[ + { + // package icon at most recent version + "icon": "", + // license at most recent version + "license": "", + // instructions at most recent version + "instructions": "", + // categories at most recent version + "categories": ["",...], + // all valid versions + "versions": ["",...], + // package dependencies + "dependency-metadata": { + // dependency package id + "": { + // name of dependency + "title": "", + // icon of dependency + "icon": "" + }, + ... + } + }, + ... +] +``` + +#### Requirements + +- if "ids" is specified, MUST only return packages in that list +- if "category" is specified, MUST NOT return packages that do not fit in that category +- MUST NOT return more than "per-page" number of packages +- all packages returned MUST be packed by an OS satisfying "eos-version-compat" +- icon MUST be a data url of the icon data +- dependency entries MUST be specified in the manifest of the package +- categories SHOULD include the categories specified by the package +- categories MAY be at the discretion of the marketplace maintainer + +### GET /latest + +#### Query Params + +- (Required) "ids": json array of package ids + +#### Returns + +```json +{ + "": null | "" + ... +} +``` + +#### Requirements + +- set of package ids in the response key set MUST be the same as the set of package ids in the query string +- if the package is not available on the marketplace its entry MUST be `null` +- if the package is available on the marketplace then its entry MUST be the highest compatible Emver for that package + +### GET /:S9PK + +#### Query Params + +- (Optional) "spec": EmverRange +- (Optional) "version-priority": "min" OR "max" + +#### Returns + +binary stream of the s9pk package data + +#### Requirements + +- the package bytes supplied MUST be the same as the package id specified in the URL. +- Content-Length MUST be specified +- if "spec" is specified, the package version returned MUST satisfy the spec in the query string +- if "version-priority" is specified to "min" AND multiple packages satisfy "spec", version returned MUST be the smallest satisfactory package version +- if "version-priority" is specified to "max" AND multiple packages satisfy "spec", version returned MUST be the largest satisfactory package version + +### GET /manifest/:PkgId + +#### Query Params + +- (Optional) "spec": EmverRange +- (Optional) "version-priority": "min" OR "max" + +#### Returns + +raw json document of the package's manifest + +#### Requirements + +- the manifest supplied MUST be the same as the package id specified in the URL. +- Content-Length MUST be specified +- if "spec" is specified, the package version returned MUST satisfy the spec in the query string +- if "version-priority" is specified to "min" AND multiple packages satisfy "spec", version returned MUST be the smallest satisfactory package version +- if "version-priority" is specified to "max" AND multiple packages satisfy "spec", version returned MUST be the largest satisfactory package version + +### GET /release-notes/:PkgId + +#### Query Params + +NONE + +#### Returns + +```json +{ + // release notes for each version + "": "" + ... +} +``` + +#### Requirements + +- All keys in this response MUST be available versions for the package +- the value for each key MUST be the release notes for that version + +### GET /icon/:PkgId + +#### Query Params + +- (Optional) "spec": EmverRange +- (Optional) "version-priority": "min" OR "max" + +#### Returns + +raw icon binary of the package + +#### Requirements + +- the icon supplied MUST be the same as the package id specified in the URL. +- Content-Length MUST be specified +- if "spec" is specified, the package version returned MUST satisfy the spec in the query string +- if "version-priority" is specified to "min" AND multiple packages satisfy "spec", version returned MUST be the smallest satisfactory package version +- if "version-priority" is specified to "max" AND multiple packages satisfy "spec", version returned MUST be the largest satisfactory package version +- Content-Type MUST be specified indicating what image type it is + +### GET /license/:PkgId + +#### Query Params + +- (Optional) "spec": EmverRange +- (Optional) "version-priority": "min" OR "max" + +#### Returns + +raw license file of the package + +#### Requirements + +- the icon supplied MUST be the same as the package id specified in the URL. +- Content-Length MUST be specified +- if "spec" is specified, the package version returned MUST satisfy the spec in the query string +- if "version-priority" is specified to "min" AND multiple packages satisfy "spec", version returned MUST be the smallest satisfactory package version +- if "version-priority" is specified to "max" AND multiple packages satisfy "spec", version returned MUST be the largest satisfactory package version + +### GET /instructions/:PkgId + +#### Query Params + +- (Optional) "spec": EmverRange +- (Optional) "version-priority": "min" OR "max" + +#### Returns + +raw instructions file of the package + +#### Requirements + +- the instructions supplied MUST be the same as the package id specified in the URL. +- Content-Length MUST be specified +- if "spec" is specified, the package version returned MUST satisfy the spec in the query string +- if "version-priority" is specified to "min" AND multiple packages satisfy "spec", version returned MUST be the smallest satisfactory package version +- if "version-priority" is specified to "max" AND multiple packages satisfy "spec", version returned MUST be the largest satisfactory package version + +### GET /version/:PkgId + +#### Query Params + +- (Optional) "spec": EmverRange +- (Optional) "version-priority": "min" OR "max" + +#### Returns + +```json +{ "version": "" } +``` + +#### Requirements + +- the version supplied MUST be a valid version for the package id specified in the URL +- if "spec" is specified, the package version returned MUST satisfy the spec in the query string +- if "version-priority" is specified to "min" AND multiple packages satisfy "spec", version returned MUST be the smallest satisfactory package version +- if "version-priority" is specified to "max" AND multiple packages satisfy "spec", version returned MUST be the largest satisfactory package version