Mods¶

Mods are game-specific entities, so all resources in this section are game-specific themselves (see: Game-specific URL prefixes).

[TODO: Flesh this section out]

GET /game/(gamedev)/(game)/mod/(moddev)/(modname)/info¶

Mod public registration info/metadata resource. Contains most info about a mod, excluding only those fields that are only for the devs. Note that the game specified by the prefix must match the game that the requested mod is registered as being applicable to.

Example request:

GET /game/thd/kag/mod/shadlington/test/info HTTP/1.1
Host: api.kag2d.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "modInfo": {
    "clientRestricted": false,
    "description": "This is an example mod",
    "devType": "individual",
    "developer": "Shadlington",
    "downloadAvailable": false,
    "fullRestricted": false,
    "gameID": 1,
    "modID": "2e6ee2d3-90eb-4772-b431-1844a06e0c53",
    "name": "Example mod",
    "nameURL": "example",
    "registered": "2013-12-11 17:59:47",
    "serverRestricted": false
  }
}

Response JSON fields:
Parameters:	moddev – mod’s developer’s name (kag username) modname – mod’s url-friendly shorthand name
Status Codes:	200 – when mod exists 404 – when mod doesn’t exist
	registered The timestamp of when the mod was first registered description A description of the mod developer The username of the mod’s developer devType Is the developer an individual or a group? gameID The ID of the game the mod is for modID The mod’s ID (may remove this) name The mod’s name nameURL The version of the mod name to use in URLs downloadAvailable Is there a download available for this mod? fullRestricted Is the full package download dev-only? serverRestricted Is the server package download dev-only? clientRestricted Is the client package download dev-only?

GET /game/(gamedev)/(game)/mod/(moddev)/(modname)/devinfo¶

Mod private registration info/metadata resource. Has nearly all mod info (only missing the devkey). Note that the game specified by the prefix must match the game that the requested mod is registered as being applicable to.

Example request:

GET /game/thd/kag/mod/shadlington/test/devinfo HTTP/1.1
Host: api.kag2d.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "modDevInfo": {
    "clientRestricted": false,
    "description": "This is an example mod",
    "devType": "individual",
    "developer": "Shadlington",
    "developerAccessList": [
      "shadlington"
    ],
    "downloadAvailable": false,
    "fullRestricted": false,
    "gameID": 1,
    "modID": "2e6ee2d3-90eb-4772-b431-1844a06e0c53",
    "name": "Example mod",
    "nameURL": "example",
    "ownerList": [
      "shadlington"
    ],
    "registered": "2013-12-11 17:59:47",
    "serverRestricted": false
  }
}

Response JSON fields:
Parameters:	moddev – mod’s developer’s name (kag username) modname – mod’s url-friendly shorthand name
Status Codes:	200 – when mod exists 404 – when mod doesn’t exist
	Most keys Same as for the mod info GET resource ownerList If the devType is individual, this is useless and just contains the developer’s name again. If the devType is group, contains a list of members of the devgroup that have ‘ownership’ of this mod and are able to modify its registration info (by making PUT requests to this resource) developerAccessList As with ownerList, only relevant for mods developed by groups. This is a list of devgroup members that are able to upload mod packages and access the mod’s devkey

PUT /game/(gamedev)/(game)/mod/(moddev)/(modname)/devinfo¶

Mod registration/metadata update resource. Uses HTTP basic auth - the username in the authorization header must either be the individual developer specified in the URL or a member of the developer group, depending on the devType. If the devType is a group then the developer must be a registered devgroup (see devgroup resources for details). Any members listed in the ownerList/developerAccessList must already be members of the devgroup assigned as the developer. Also, the person making the change cannot remove themselves from the ownerList (only people in the ownerList are able to make PUT requests to this resource). Also, anyone who is a member of the devgroup’s own ownerList is able to make PUT requests to this resource regardless of whether or not they are already on the mod’s ownerList, but in order to do so they must add themselves to the mod ownerList. Note that the mod will be set as being applicable to the game that is specified in the prefix.

Example requests:

PUT /game/thd/kag/mod/shadlington/test/devinfo HTTP/1.1
Host: api.kag2d.com
Content-Type: application/json

{
  "modInfo": {
    "clientRestricted": false,
    "description": "This is a test mod",
    "devType": "individual",
    "developer": "shadlington",
    "developerAccessList": ["shadlington"],
    "fullRestricted": false,
    "name": "Test mod",
    "nameURL": "testtttttttt",
    "ownerList": ["shadlington"],
    "serverRestricted": false
  }
}

PUT /game/thd/kag/mod/shadlington/test/devinfo HTTP/1.1
Host: api.kag2d.com
Content-Type: application/json

{
  "modInfo": {
    "clientRestricted": false,
    "description": "This is a test mod",
    "devType": "group",
    "developer": "thd",
    "developerAccessList": ["mm"],
    "fullRestricted": false,
    "name": "Test mod",
    "nameURL": "testtttttttt",
    "ownerList": ["mm", "shadlington"],
    "serverRestricted": false
  }
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{}

Request JSON fields:
Parameters:	moddev – mod’s developer’s name (kag username) modname – mod’s url-friendly shorthand name
Status Codes:	200 – when mod info update is successful 400 – when there is anything invalid about the request body 401 – when the authorization headers are missing/invalid 403 – when the auth header username doesn’t match the developer in the URL/isn’t a member of the devgroup (or the player is inactive), or you try to remove yourself from the ownerList, or you try to change the nameURL.
	modInfo Same as for the mod devinfo GET resource

DELETE /game/(gamedev)/(game)/mod/(moddev)/(modname)/devinfo¶

Mod deletion resource. Uses HTTP basic auth - the username in the authorization header must match the username of the developer in the URL. This will delete the entire mod - its registration info and any uploaded packages, if it has them.

Example request:

DELETE /game/thd/kag/mod/shadlington/test/devinfo HTTP/1.1
Host: api.kag2d.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{}

Parameters:	moddev – mod’s developer’s name (kag username) modname – mod’s url-friendly shorthand name
Status Codes:	200 – when the mod exists and the deletion is successful 401 – when the authorization headers are missing/invalid 403 – when the auth header username doesn’t match the developer in the URL 404 – when mod doesn’t exist

GET /game/(gamedev)/(game)/mod/(moddev)/(modname)/devkey¶

Mod developer key resource. Uses HTTP basic auth - the username in the authorization header must match the username of the developer in the URL. Note that the game specified by the prefix must match the game that the requested mod is registered as being applicable to. This developer key should be kept private as it is used to ‘sign’ mods. Only people on the mod’s developerAccessList can access this resource.

Example request:

GET /game/thd/kag/mod/shadlington/test/devkey HTTP/1.1
Host: api.kag2d.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "modDevkey": "bc6abf221a7b46f660244324d2ba7d"
}

Response JSON fields:
Parameters:	moddev – mod’s developer’s name (kag username) modname – mod’s url-friendly shorthand name
Status Codes:	200 – when mod exists 401 – when the authorization headers are missing/invalid 403 – when the auth header username doesn’t match the developer in the URL 404 – when mod doesn’t exist
	modDevkey The mod’s developer key

POST /game/(gamedev)/(game)/mod/(moddev)/(modname)/verifyhash¶

Mod hash verification resource. Note that the game specified by the prefix must match the game that the requested mod is registered as being applicable to. If the localHash provided matches the devHash provided (after the localHash is re-hashed with the mod’s developer key as a salt) then the resource will return a validHash value of true. Otherwise, it’ll return false.

Example request:

POST /game/thd/kag/mod/shadlington/test/verifyhash HTTP/1.1
Host: api.kag2d.com
Content-Type: application/json

{
  'devHash': "s7s63h4yf883",
  'localHash': "sk84ufjstgh3ki"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "validHash": false
}

Request JSON fields:
Parameters:	moddev – mod’s developer’s name (kag username) modname – mod’s url-friendly shorthand name
Status Codes:	200 – when the mod exists 400 – when either hash key is missing or not a string 404 – when mod doesn’t exist
	validHash Boolean - if the hashes matched or not (after re-hashing the localHash with the mod devkey as a salt)

GET /game/(gamedev)/(game)/mod/(moddev)/(modname)/full¶

Mod package retrieval resource. When successful (i.e. 200) the response body is a .tar.gz file. Specifically, this resource is for the whole package, including both server-specific and client-specific files. Note that the game specified by the prefix must match the game that the requested mod is registered as being applicable to. If this package type is restricted then only the developer/members of the devgroup may access this resource.

Example request:

GET /game/thd/kag/mod/shadlington/test/full HTTP/1.1
Host: api.kag2d.com
Accept: application/x-tar

Example response:

HTTP/1.1 200 OK
Content-Type: application/x-tar
Content-Encoding: gzip

[Some .tar.gz file data]

Parameters:	moddev – mod’s developer’s name (kag username) modname – mod’s url-friendly shorthand name
Status Codes:	200 – when mod is registered and its package exists 404 – when mod is not registered and has no package

PUT /game/(gamedev)/(game)/mod/(moddev)/(modname)/full¶

Mod package update resource. Note that the game specified by the prefix must match the game that the requested mod is registered as being applicable to. It is advised that you generate your package using a client as it must contain a registration.json file that meets several requirements in order to be accepted. Only people on the mod’s developerAccessList can update this resource.

Example request:

PUT /game/thd/kag/mod/shadlington/test/full HTTP/1.1
Host: api.kag2d.com
Content-Type: application/x-tar

[Some .tar.gz file data]

Example response:

HTTP/1.1 200 OK
Content-Type: application/x-tar

{
  "statusMessage": "Mod package saved successfully"
}

Parameters:

moddev – mod’s developer’s name (kag username)
modname – mod’s url-friendly shorthand name

Status Codes:

200 – when mod package update is successful
400 – one of the following reasons: the package doesn’t contain a valid registration.json file at the root; the reg file has the wrong hash; the reg file is missing keys; the reg file has values that don’t match the mod’s registered data; the package contains no files of a type that is valid for inclusion in a mod (.as, .png, .ogg, .cfg).
401 – when the authorization headers are missing/invalid
403 – when the auth header username isn’t the mod developer.
404 – when mod you’re trying to update doesn’t exist yet
415 – when the data sent isn’t a valid .tar.gz file

GET /game/(gamedev)/(game)/mod/(moddev)/(modname)/server¶

Mod package retrieval resource. When successful (i.e. 200) the response body is a .tar.gz file. Specifically, this resource is for the server package, excluding any client-specific files. Note that the game specified by the prefix must match the game that the requested mod is registered as being applicable to. If this package type is restricted then only the developer/members of the devgroup may access this resource.

Example request:

GET /game/thd/kag/mod/shadlington/test/server HTTP/1.1
Host: api.kag2d.com
Accept: application/x-tar

Example response:

HTTP/1.1 200 OK
Content-Type: application/x-tar
Content-Encoding: gzip

[Some .tar.gz file data]

Parameters:	moddev – mod’s developer’s name (kag username) modname – mod’s url-friendly shorthand name
Status Codes:	200 – when mod is registered and its package exists 404 – when mod is not registered and has no package

GET /game/(gamedev)/(game)/mod/(moddev)/(modname)/client¶

Mod package retrieval resource. When successful (i.e. 200) the response body is a .tar.gz file. Specifically, this resource is for the client package, excluding any server-specific files. Note that the game specified by the prefix must match the game that the requested mod is registered as being applicable to. If this package type is restricted then only the developer/members of the devgroup may access this resource.

Example request:

GET /game/thd/kag/mod/shadlington/test/client HTTP/1.1
Host: api.kag2d.com
Accept: application/x-tar

Example response:

HTTP/1.1 200 OK
Content-Type: application/x-tar
Content-Encoding: gzip

[Some .tar.gz file data]

Parameters:	moddev – mod’s developer’s name (kag username) modname – mod’s url-friendly shorthand name
Status Codes:	200 – when mod is registered and its package exists 404 – when mod is not registered and has no package

GET /game/(gamedev)/(game)/mods¶

Mod list resource. This is a list resource and therefore the notes in the introduction concerning list resources are relevant here: List type resources. Note that the mod list will be filtered down to mods registered as applicable to the game specified by the prefix.

Example URL:

/game/thd/kag/mods?filters=[{“field”: “developer”, “op”: “eq”, “value”: “Shadlington”}]&limit=5&start=10

Example request:

GET /game/thd/kag/mods HTTP/1.1
Host: api.kag2d.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "modList": [
    {
      "clientRestricted": false,
      "description": "This is an example mod",
      "devType": "individual",
      "developer": "Shadlington",
      "downloadAvailable": false,
      "fullRestricted": false,
      "gameID": 1,
      "modID": "2e6ee2d3-90eb-4772-b431-1844a06e0c53",
      "name": "Example mod",
      "nameURL": "example",
      "registered": "2013-12-11 17:59:47",
      "serverRestricted": false
    },
    {
      anothermod (same format as above)
    }
  ]
}

Query Parameters:
	start (variable) – which mod list result to start from limit (variable) – how many mods to retrieve from the list filters (variable) – The filters to apply to the mod list
Status Codes:	200 – most of the time 400 – when the filters/limit/start are invalid in any way
Response JSON fields:
	modList List of mods that match the filter criteria provided. Contents are the same as for the mod info resource.

GET /game/(gamedev)/(game)/mods/filterinfo¶

Mod list filter info resource This is a list filterinfo resource and therefore the notes in the introduction concerning list resources are relevant here: List type resources. Note that the game prefix currently doesn’t do anything for this resource (though will eventually cause the resource to return only the filters relevant to the specified game).

Example request:

GET /game/thd/kag/mods/filterinfo HTTP/1.1
Host: api.kag2d.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "modListFilterFields": [
    {
      "name": "gameID",
      "type": "int"
    },
    {
      "name": "name",
      "type": "string"
    },
    {
      "name": "downloadAvailable",
      "type": "int"
    },
    {
      "name": "registered",
      "type": "datetime"
    },
    {
      "name": "clientRestricted",
      "type": "int"
    },
    {
      "name": "devType",
      "type": "int"
    },
    {
      "name": "last_modified",
      "type": "datetime"
    },
    {
      "name": "serverRestricted",
      "type": "int"
    },
    {
      "name": "modID",
      "type": "string"
    },
    {
      "name": "fullRestricted",
      "type": "int"
    },
    {
      "name": "nameURL",
      "type": "string"
    },
    {
      "name": "devkey",
      "type": "string"
    },
    {
      "name": "description",
      "type": "string"
    },
    {
      "name": "developer",
      "ops": "eq",
      "type": "string"
    }
  ],
  "modListFilterOperators": [
    {
      "meaning": ">",
      "name": "gt"
    },
    {
      "meaning": "<",
      "name": "lt"
    },
    {
      "meaning": "!=",
      "name": "ne"
    },
    {
      "meaning": ">=",
      "name": "ge"
    },
    {
      "meaning": "<=",
      "name": "le"
    },
    {
      "meaning": "=",
      "name": "eq"
    }
  ]
}

Response JSON fields:
Status Codes:	200 – always (ideally)
	modListFilterFields The fields that you can filter the mod list by, with their types modListFilterOperators The operators that you can filter the mod list with, with their meanings (underlying operator)

Navigation

Mods¶

Related Topics

Quick search