REST API Client

This is the documentation of the REST API CLI client to work with the Customfield Editor for Jira's REST API Endpoints. The Client will not provide all features of the REST API. It is meant as a reference implementation of the most common features to show you how to use the API. You will need to take further action to implement your own client. Check out the Source Code at GitHub which will help you to do so. The API Client is provided under the MIT License without any warranty.

Prerequisites

You need to have Python 3.2+ and Git installed and on PATH. The commands should print these or similiar versions.

$
python --version
Python 3.4.3
$
pip --version
pip 6.0.8 from ....
$
git --version
git version 2.6.3.windows.1

Installing the REST API CLI Client

Now clone the demo python project into the newcep-clientdirectory.

$
git clone --single-branch --branch cep-client https://github.com/codeclou/customfield-editor-plugin.git cep-client

Now change into the checked out directory and install the client.

$
cd cep-client
$
python setup.py install

Now you can run the client anyhwere.

$
cep-client -h

You can check out the source code in the GitHub Project

Using the client with field type: Select List (single choice)

We want to insert three values (windows, linux and mac) into the select field and set mac as default value. Therefore save the following file to you homedir. After the inserting we want to sort the options ascending.

options-to-insert--select.json
[
    {
        "optionvalue" : "windows"
    },
    {
        "optionvalue" : "linux"
    },
    {
        "optionvalue" : "mac",
        "default": true
    }
]
  1. Create Single Select Field

    Create a new single select field calledclientTestSingleSelectusing the Jira Administration interface.

  2. List Customfields as admin

    Now we list all admin fields with a jira-administrator user.

    $
    cep-client -a adminListFields -url http://localhost:2990/jira -user admin -pass admin
    ~~ REST API Client for Customfield Editor for Jira ~~ v1.2rc1
    
    > initializing
      ✓ UserInput is valid.
      ✓ ApiHelper initialized.
    
    # Action: adminListFields
    
    > GET http://localhost:2990/jira/rest/jiracustomfieldeditorplugin/1.2/admin/customfields
      ✓ request successful
      fieldName                             fieldId  fieldType        fieldDescription
      ----------------------------------  ---------  ---------------  ------------------
      clientTestSingleSelect                  10000  select
      cascadingselect                         10001  cascadingselect
      textfield                               10002  textfield
    
      ✓ EXIT gracefully

    And we see that ourclientTestSingleSelecthas the field ID 10000.

  3. Grant permissions on field as admin

    Since we want to work on user-level with the fields we need to grant bob and linda rights on the customfield.

    $
    cep-client -a adminGrantPermission --customFieldId 10000 --userList linda bob  -url http://localhost:2990/jira -user admin -pass admin
    ~~ REST API Client for Customfield Editor for Jira ~~ v1.2rc1
    
    > initializing
      ✓ UserInput is valid.
      ✓ ApiHelper initialized.
    
    # Action: adminGrantPermission
    
    > GET http://localhost:2990/jira/rest/jiracustomfieldeditorplugin/1.2/admin/customfields/10000
      ✓ request successful
      permissions BEFORE grant:
      userlist    grouplist
      ----------  -----------
      steve       jira-users
    
    
    > PUT http://localhost:2990/jira/rest/jiracustomfieldeditorplugin/1.2/admin/customfields/10000
      ✓ request successful
      permissions AFTER grant:
      userlist    grouplist
      ----------  -----------
      bob         jira-users
      steve
      linda
    
    
      ✓ EXIT gracefully
  4. List Customfields as bob

    We just granted permissions to bob and now we want to list customfields as user bob.

    $
    cep-client -a userListFields -url http://localhost:2990/jira -user bob -pass 5678
    ~~ REST API Client for Customfield Editor for Jira ~~ v1.2rc1
    
    > initializing
      ✓ UserInput is valid.
      ✓ ApiHelper initialized.
    
    # Action: userListFields
    
    > GET http://localhost:2990/jira/rest/jiracustomfieldeditorplugin/1.2/user/customfields
      ✓ request successful
      fieldName                             fieldId  fieldDescription    fieldType
      ----------------------------------  ---------  ------------------  ---------------
      clientTestSingleSelect                  10000                      cascadingselect
    
    
      ✓ EXIT gracefully
  5. Insert Options into Customfield 10000 as bob

    We now want insert options intoclientTestSingleSelectfield with user bob.

    $
    cep-client -a userInsertOptions --customFieldId 10000 -f ./test-data/options-to-insert--select.json -url http://localhost:2990/jira -user bob -pass 5678
    ~~ REST API Client for Customfield Editor for Jira ~~ v1.2rc1
    
    > initializing
      ✓ UserInput is valid.
      ✓ ApiHelper initialized.
    
    # Action: userInsertOptions
      optionvalue    default
      -------------  ---------
      windows
      linux
      mac            true
    
    > POST http://localhost:2990/jira/rest/jiracustomfieldeditorplugin/1.2/user/customfields/10000/contexts/default/options
      {'disabled': False, 'id': 12040, 'optionvalue': 'windows', 'sequence': 2}
    
    > POST http://localhost:2990/jira/rest/jiracustomfieldeditorplugin/1.2/user/customfields/10000/contexts/default/options
      {'disabled': False, 'id': 12040, 'optionvalue': 'linux', 'sequence': 3}
    
    > POST http://localhost:2990/jira/rest/jiracustomfieldeditorplugin/1.2/user/customfields/10000/contexts/default/options
      {'disabled': False, 'id': 12040, 'optionvalue': 'mac', 'sequence': 4}
    
    > PUT http://localhost:2990/jira/rest/jiracustomfieldeditorplugin/1.2/user/customfields/10000/contexts/default/options/default
    
    
      ✓ EXIT gracefully
  6. Confirm inserted Options of Customfield 10000 as bob

    We now want to list options ofclientTestSingleSelectfield with user bob to confirm our options have been inserted.

    $
    cep-client -a userListOptions --customFieldId 10000 -url http://localhost:2990/jira -user bob -pass 5678
    ~~ REST API Client for Customfield Editor for Jira ~~ v1.2rc1
    
    > initializing
      ✓ UserInput is valid.
      ✓ ApiHelper initialized.
    
    # Action: userListOptions
    
    > GET http://localhost:2990/jira/rest/jiracustomfieldeditorplugin/1.2/user/customfields/10000/contexts/default/options
      ✓ request successful
         id  optionvalue          sequence    disabled
      -----  -----------------  ----------  ----------
      10005  foo                         0           0
      10006  bar                         1           0
      10007  windows                     2           0
      10008  linux                       3           0
      10009  mac                         4           0
    
    
      ✓ EXIT gracefully
  7. Alphabetical Sorting of Options of Customfield 10000 as bob

    We now want to sort options ofclientTestSingleSelectfield ascending as user bob.

    $
    cep-client -a userSortOptions --customFieldId 10000 --order ASCENDING -url http://localhost:2990/jira -user bob -pass 5678
    ~~ REST API Client for Customfield Editor for Jira ~~ v1.2rc1
    
    > initializing
      ✓ UserInput is valid.
      ✓ ApiHelper initialized.
    
    # Action: userSortOptions
    
    > PUT http://localhost:2990/jira/rest/jiracustomfieldeditorplugin/1.2/user/customfields/10000/contexts/default/options/sort
    
    
      ✓ EXIT gracefully
  8. Confirm sorting of Options on Customfield 10000 as bob

    We now want to list options ofclientTestSingleSelectfield with user bob to confirm the new sort order.

    $
    cep-client -a userListOptions --customFieldId 10000 -url http://localhost:2990/jira -user bob -pass 5678
    ~~ REST API Client for Customfield Editor for Jira ~~ v1.2rc1
    
    > initializing
      ✓ UserInput is valid.
      ✓ ApiHelper initialized.
    
    # Action: userListOptions
    
    > GET http://localhost:2990/jira/rest/jiracustomfieldeditorplugin/1.2/user/customfields/10000/contexts/default/options
      ✓ request successful
         id  optionvalue          sequence    disabled
      -----  -----------------  ----------  ----------
      10005  bar                         0           0
      10006  foo                         1           0
      10007  linux                       2           0
      10008  mac                         3           0
      10009  windows                     4           0
    
    
      ✓ EXIT gracefully