<< Back to GForge REST API

Entity: Setting

GET

getSetting

Searches for settings matching criteria, or retrieves a specific setting by database ID.

Parameters (5)

Name Type Description
id int Unique identifier for the setting record. ThisIf this value is specified, others will be ignored.
section string Section to filter results with. Examples are "project", "tracker", "trackeritem"
refId int Unique identifier for the $section being referenced. For $section = "project", $refId would be the project ID. Unixnames are not allowed.
settingName string Name of the setting to be retrieved.
defaultValue string If a record is not found, return this value instead. If none is specified, the method will return 404 (Not Found). Note: If $defaultValue is specified and no record is found, the response data will not include the id or project values.
Sortable
Use the sort_field and sort_dir parameters to control the order in which records are returned.
Pageable
Use the page_size and page_num parameters to control the set of records returned.

Return: \gforge\core\models\api\SettingBasic

Zero or more SettingBasic records for a search. Zero or one SettingBasic record for an id retrieval.

Name Type Description
section string Section or Object type to which the setting belongs to
refId int ID of the referenced item
settingName string Name of the setting
settingValue mixed Value of the setting. If it was stored serialized variable contains unserialized object.
api_url \API URL to obtain this Setting record

Example 1

Find a setting by database ID:
  GET http://api.mygforge.tld/setting/125

{
   "id":125,
   "refId":"43",
   "section":"tracker",
   "settingName":"some_setting",
   "settingValue":"1"
}

Example 2

Fetch a setting by refId, Section and Setting Name:
  GET http://api.mygforge.tld/setting?refId=43§ion=tracker&settingName=some_setting

{
   "id":125,
   "refId":"43",
   "section":"tracker",
   "settingName":"some_setting",
   "settingValue":"1"
}

POST

postSetting

Creates or updates a Setting record. Only admin users can POST.
Returns a SettingBasic structure with updated values if the setting was created or exists and was updated. If invalid data was provided throws a 400 (Bad Request) code with a JSON-encoded list of validation issues. If the setting does not exist, a 404 (NotFoundException) is thrown.

The following parameters are expected in the Request object:

  • int $id Database identifier for the setting record. Always ignored in favor of the URL.
  • int $referenceId Unique identifier of the referenced object (object to which the setting applies)
  • string $section Identifies the object type (tracker item, tracker, document, etc)
  • string $settingName Name (or "key") of the setting
  • string $settingValue Value for the setting

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Request object

Return: array

with url location

PUT

putSetting

Updates a whole object. For all purposes it works in the same way than POST, so we are redirecting to that method.

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Request object

Return: array

containing url location

DELETE

deleteSetting

Deletes a Setting model from db. It's required that Request contains the following parameters: section, refId, settingName. If the record is not found a 404 exception is thrown.

Parameters (1)

Name Type Description
request \mvcnphp\RequestParameters Request object.

Return: int

1 on success