From 92bc6717683dc6c63b9e61fcae515e3b2a5e3fcc Mon Sep 17 00:00:00 2001 From: awuctl Date: Wed, 11 Mar 2020 10:27:18 +0100 Subject: [PATCH 1/4] Improved readme --- readme.md | 52 ++++++++++++++++++++++++++++------------------------ 1 file changed, 28 insertions(+), 24 deletions(-) diff --git a/readme.md b/readme.md index d5dadd0..61455b0 100644 --- a/readme.md +++ b/readme.md @@ -2,11 +2,11 @@ UUP dump JSON API ----------------- ### Description -A simple endpoint allowing access of the UUP dump API using HTTP requests. +A simple endpoint allowing access to the UUP dump API using simple HTTP GET requests. ### Usage All requests are done using GET requests with parameters specified in the URL. -Response is provided as an JSON. +Responses are provided in JSON format. Example response: ```json @@ -36,68 +36,72 @@ Parameters: - None #### `/listid.php` -Returns a list of builds in the local database. +Returns a list of builds in the local database. (like "Browse the list of known builds" on the website) Parameters: - - `search` - Search query (optional) + - `search` - Optional search query - **Supported values:** any text - - `sortByDate` - Sort results by creation date (optional) + - `sortByDate` - Optional sorting results by creation date - **Supported values:** 0 = Disable, 1 = Enable #### `/fetchupd.php` Fetches the latest builds from Windows Update servers using specified -parameters. +parameters. (like "Fetch the latest build" on the website) Parameters: - - `arch` - Architecture of build to find + - `arch` - Specifies which architecture the API will return. - **Supported values:** `amd64`, `arm64`, `x86` - - `ring` - Ring to use when fetching information + - `ring` - Specifies the ring the API uses when querying Windows Update servers. - **Supported values:** `WIF`, `WIS`, `RP`, `RETAIL` + - `WIF` - Windows Insider Fast + - `WIS` - Windows Insider Slow + - `RP` - Release Preview + - `RETAIL` - Retail - `flight` - Flight to use when fetching information - **Supported values:** `Active`, `Skip`, `Current` - **NOTE:** `Skip` is for `WIF` ring only. `Current` is for `RP` ring only. - - `build` - Build number to use when fetching information + - `build` - Build number to use by the API when fetching information - **Supported values:** >= 9841 and <= PHP_INT_MAX-1 - `sku` - SKU number to use when fetching information - - **Supported values:** Any integer + - **Supported values:** Any SKU integer #### `/get.php` Retrieves download links for specified Update ID and provides lists of ready to use UUP sets. Parameters: - - `id` - Update identifier - - **Supported values:** any update identifier + - `id` - Update identifier (UUIDv4 string) + - **Supported values:** Any valid update identifier in the UUIDv4 format. - `lang` - Create UUP set for selected language (optional) - **Supported values:** language name in xx-xx format - - `edition` - Create UUP set for selected edition (optional) - - **Supported values:** any edition name - - **NOTE:** You need to specify `lang` to get successful request + - `edition` - Create UUP set for the selected edition (optional) + - **Supported values:** Any edition name + - **NOTE:** Must be used with `lang` - - `noLinks` - Do not retrieve download links for created UUP set (optional) + - `noLinks` - Do not retrieve download links for the created UUP set (optional) - **Supported values:** 0 = Disable, 1 = Enable #### `/listlangs.php` -Lists available languages for specified Update ID +Lists available languages for the specified Update ID. Parameters: - - `id` - Update identifier (optional) - - **Supported values:** any update identifier + - `id` - Optional Update identifier (UUIDv4 string) + - **Supported values:** Any valid update identifier in the UUIDv4 format. #### `/listlangs.php` -Lists available editions for specified Update ID +Lists available editions for the specified Update ID. Parameters: - - `lang` - Generate list for selected language - - **Supported values:** language name in xx-xx format +- `lang` - Generate edition list for the selected language + - **Supported values:** Language name in xx-xx format - - `id` - Update identifier (optional) - - **Supported values:** any update identifier + - `id` - Optional update identifier (UUIDv4 string) + - **Supported values:** Any valid update identifier in the UUIDv4 format. From 06ec2ec184d379e011a06a04ee1798a3cf64834d Mon Sep 17 00:00:00 2001 From: awuctl Date: Wed, 11 Mar 2020 12:06:26 +0100 Subject: [PATCH 2/4] Improved readme, added JSON response formats --- readme.md | 153 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 128 insertions(+), 25 deletions(-) diff --git a/readme.md b/readme.md index 61455b0..0abc96e 100644 --- a/readme.md +++ b/readme.md @@ -1,23 +1,13 @@ -UUP dump JSON API +# UUP dump JSON API ----------------- -### Description +## Description A simple endpoint allowing access to the UUP dump API using simple HTTP GET requests. -### Usage +## Usage All requests are done using GET requests with parameters specified in the URL. Responses are provided in JSON format. -Example response: -```json -{ - "response": { - "apiVersion": "1.27.0" - }, - "jsonApiVersion": "0.1.0-alpha" -} -``` - Responses from the UUP dump API are always returned in the `response` key. If request fails, a HTTP error code will be set to: @@ -28,14 +18,24 @@ If request fails, a HTTP error code will be set to: In such cases `response` key will contain an `error` key with short description of the error. -### Supported endpoints -#### `/` or `/index.php` -Returns versions of APIs +## Supported endpoints +### `/` or `/index.php` +Returns versions of both JSON and UUP dump APIs Parameters: - None -#### `/listid.php` +#### JSON response format: +```json +{ + "response": { + "apiVersion":"string" // Current UUP dump API version + }, + "jsonApiVersion": "string" // Current JSON API version +} +``` + +### `/listid.php` Returns a list of builds in the local database. (like "Browse the list of known builds" on the website) Parameters: @@ -45,7 +45,27 @@ Parameters: - `sortByDate` - Optional sorting results by creation date - **Supported values:** 0 = Disable, 1 = Enable -#### `/fetchupd.php` +#### JSON response format: +```json +{ + "response": { + "apiVersion":"string", // Current UUP dump API version + "builds": [ + { + "title": "string", // Update title, for example Windows 10 Insider Preview 19577.1000 (rs_prerelease) + "build": "string", // Update build number, for example 19577.1000 + "arch": " string", // Update architecture, for example amd64 + "created": 1234567890, // Timestamp of when the build was added to the database + "uuid": "string" // UUIDv4 Update Identifier + }, + ... + ] + }, + "jsonApiVersion": "string" // Current JSON API version +} +``` + +### `/fetchupd.php` Fetches the latest builds from Windows Update servers using specified parameters. (like "Fetch the latest build" on the website) @@ -70,7 +90,31 @@ Parameters: - `sku` - SKU number to use when fetching information - **Supported values:** Any SKU integer -#### `/get.php` +#### JSON response format: +```json +{ + "response": { + "apiVersion": "string", // Current UUP dump API version + "updateId": "string", // UUIDv4 Update Identifier + "updateTitle": "string", // Update title, such as Windows 10 Insider Preview 19577.1000 (rs_prerelease) + "foundBuild": "string", // Update build number, such as 19577.1000 + "arch": "string", // Update architecture, such as amd64/x86/arm64 + "fileWrite": "string", // NO_SAVE if the build was already in the database, INFO_WRITTEN if it was just added to it. + "updateArray": [ + { + "updateId": "string", // UUIDv4 Update Identifier + "updateTitle": "string", // Update title, such as Windows 10 Insider Preview 19577.1000 (rs_prerelease) + "foundBuild": "string", // Update build number, such as 19577.1000 + "arch": "string", // Update architecture, such as amd64/x86/arm64 + "fileWrite": "string" // NO_SAVE if the build was already in the database, INFO_WRITTEN if it was just added to it. + } + ] + }, + "jsonApiVersion": "string" // Current JSON API version +} +``` + +### `/get.php` Retrieves download links for specified Update ID and provides lists of ready to use UUP sets. @@ -79,24 +123,65 @@ Parameters: - **Supported values:** Any valid update identifier in the UUIDv4 format. - `lang` - Create UUP set for selected language (optional) - - **Supported values:** language name in xx-xx format + - **Supported values:** Language name in xx-xx format. - `edition` - Create UUP set for the selected edition (optional) - - **Supported values:** Any edition name - - **NOTE:** Must be used with `lang` + - **Supported values:** Any edition name. + - **NOTE:** Must be used with `lang`. - `noLinks` - Do not retrieve download links for the created UUP set (optional) - - **Supported values:** 0 = Disable, 1 = Enable + - **Supported values:** 0 = Disable (Retrieve links), 1 = Enable (No links) -#### `/listlangs.php` +#### JSON response format: +```json +{ + "response": { + "apiVersion": "string", // Current UUP dump API version + "updateName": "string", // Update title, such as Windows 10 Insider Preview 19577.1000 (rs_prerelease) + "arch": "string", // Update architecture, for example x86 + "build": "string", // Update build number, for example 19577.1000 + "files": { // All files contained in the package + "string": { // File name, such as 'core_en-us.esd', 'microsoft-windows-client-features-package.esd', etc. + "sha1": "string", // The file's SHA1 checksum. + "size": "string", // File size in bytes + "url": "string", // File download link, 'null' if noLinks=1 + "uuid": "string", // File UUIDv4, 'null' if noLinks=1 used + "expire": "string", // Link expiration date, '0' if noLinks=1 used + "debug": "string" // Raw data from Microsoft servers, 'null' if noLinks=1 used + }, + ... + } + }, + "jsonApiVersion": "string" // Current JSON API version +} +``` + +### `/listlangs.php` Lists available languages for the specified Update ID. Parameters: - `id` - Optional Update identifier (UUIDv4 string) - **Supported values:** Any valid update identifier in the UUIDv4 format. +#### JSON response format: +```json +{ + "response": { + "apiVersion": "string", // Current UUP dump API version + "langList": [ + "en-gb", // Short language name, xx-xx format. + ... + ], + "langFancyNames": { + "en-gb": "English (United Kingdom)", // key-value pairs of xx-xx to full language name. + ... + } + }, + "jsonApiVersion": "string" // Current JSON API version +} +``` -#### `/listlangs.php` +### `/listeditions.php` Lists available editions for the specified Update ID. Parameters: @@ -105,3 +190,21 @@ Parameters: - `id` - Optional update identifier (UUIDv4 string) - **Supported values:** Any valid update identifier in the UUIDv4 format. + +#### JSON response format: +```json +{ + "response": { + "apiVersion": "string", // Current UUP dump API version + "editionList": [ + "CLOUD", // Short edition name + ... + ], + "editionFancyNames": { + "CLOUD": "Windows 10 S", // key-value pairs of edition name to fancy edition name. + ... + } + }, + "jsonApiVersion": "string" // Current JSON API version +} +``` From 72dd387e3ae4778562a59805a21d825516b643d3 Mon Sep 17 00:00:00 2001 From: awuctl <61098069+awuctl@users.noreply.github.com> Date: Wed, 11 Mar 2020 12:10:00 +0100 Subject: [PATCH 3/4] Change readme code samples' language to JavaScript --- readme.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/readme.md b/readme.md index 0abc96e..be03af1 100644 --- a/readme.md +++ b/readme.md @@ -26,7 +26,7 @@ Parameters: - None #### JSON response format: -```json +```javascript { "response": { "apiVersion":"string" // Current UUP dump API version @@ -46,7 +46,7 @@ Parameters: - **Supported values:** 0 = Disable, 1 = Enable #### JSON response format: -```json +```javascript { "response": { "apiVersion":"string", // Current UUP dump API version @@ -91,7 +91,7 @@ Parameters: - **Supported values:** Any SKU integer #### JSON response format: -```json +```javascript { "response": { "apiVersion": "string", // Current UUP dump API version @@ -133,7 +133,7 @@ Parameters: - **Supported values:** 0 = Disable (Retrieve links), 1 = Enable (No links) #### JSON response format: -```json +```javascript { "response": { "apiVersion": "string", // Current UUP dump API version @@ -164,7 +164,7 @@ Parameters: - **Supported values:** Any valid update identifier in the UUIDv4 format. #### JSON response format: -```json +```javascript { "response": { "apiVersion": "string", // Current UUP dump API version @@ -192,7 +192,7 @@ Parameters: - **Supported values:** Any valid update identifier in the UUIDv4 format. #### JSON response format: -```json +```javascript { "response": { "apiVersion": "string", // Current UUP dump API version From 63b40fb19f8fe60580048a3df67927bfb5cdfc46 Mon Sep 17 00:00:00 2001 From: awuctl <61098069+awuctl@users.noreply.github.com> Date: Wed, 11 Mar 2020 19:33:22 +0100 Subject: [PATCH 4/4] Changed UUID information, removed header underline --- readme.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/readme.md b/readme.md index be03af1..39bca8b 100644 --- a/readme.md +++ b/readme.md @@ -1,5 +1,4 @@ # UUP dump JSON API ------------------ ## Description A simple endpoint allowing access to the UUP dump API using simple HTTP GET requests. @@ -56,7 +55,7 @@ Parameters: "build": "string", // Update build number, for example 19577.1000 "arch": " string", // Update architecture, for example amd64 "created": 1234567890, // Timestamp of when the build was added to the database - "uuid": "string" // UUIDv4 Update Identifier + "uuid": "string" // UUID Update Identifier }, ... ] @@ -95,14 +94,14 @@ Parameters: { "response": { "apiVersion": "string", // Current UUP dump API version - "updateId": "string", // UUIDv4 Update Identifier + "updateId": "string", // UUID Update Identifier "updateTitle": "string", // Update title, such as Windows 10 Insider Preview 19577.1000 (rs_prerelease) "foundBuild": "string", // Update build number, such as 19577.1000 "arch": "string", // Update architecture, such as amd64/x86/arm64 "fileWrite": "string", // NO_SAVE if the build was already in the database, INFO_WRITTEN if it was just added to it. "updateArray": [ { - "updateId": "string", // UUIDv4 Update Identifier + "updateId": "string", // UUID Update Identifier "updateTitle": "string", // Update title, such as Windows 10 Insider Preview 19577.1000 (rs_prerelease) "foundBuild": "string", // Update build number, such as 19577.1000 "arch": "string", // Update architecture, such as amd64/x86/arm64 @@ -119,8 +118,8 @@ Retrieves download links for specified Update ID and provides lists of ready to use UUP sets. Parameters: - - `id` - Update identifier (UUIDv4 string) - - **Supported values:** Any valid update identifier in the UUIDv4 format. + - `id` - Update identifier (UUID string) + - **Supported values:** Any valid update identifier in the UUID format, may include revision in the following format: "UUID_rev.2". - `lang` - Create UUP set for selected language (optional) - **Supported values:** Language name in xx-xx format. @@ -160,8 +159,8 @@ Parameters: Lists available languages for the specified Update ID. Parameters: - - `id` - Optional Update identifier (UUIDv4 string) - - **Supported values:** Any valid update identifier in the UUIDv4 format. + - `id` - Optional Update identifier (UUID string) + - **Supported values:** Any valid update identifier in the UUID format, may include revision in the following format: "UUID_rev.2". #### JSON response format: ```javascript @@ -188,8 +187,8 @@ Parameters: - `lang` - Generate edition list for the selected language - **Supported values:** Language name in xx-xx format - - `id` - Optional update identifier (UUIDv4 string) - - **Supported values:** Any valid update identifier in the UUIDv4 format. + - `id` - Optional update identifier (UUID string) + - **Supported values:** Any valid update identifier in the UUID format, may include revision in the following format: "UUID_rev.2". #### JSON response format: ```javascript