NAME
    RT::Extension::REST2 - Adds a modern REST API to RT under /REST/2.0/

RT VERSION
    Works with RT 4.4.

    REST2 is core in RT 5.0.0 and later, so you do not need this extension
    for those versions.

INSTALLATION
    perl Makefile.PL
    make
    make install
        May need root permissions

    Edit your /opt/rt4/etc/RT_SiteConfig.pm
        Add this line:

            Plugin('RT::Extension::REST2');

    Clear your mason cache
            rm -rf /opt/rt4/var/mason_data/obj

    Restart your webserver

USAGE
  Tutorial
    To make it easier to authenticate to REST2, we recommend installing
    RT::Authen::Token. Visit "Logged in as ___" -> Settings -> Auth Tokens.
    Create an Auth Token, give it any description (such as "REST2 with
    curl"). Make note of the authentication token it provides to you.

    For other authentication options see the section "Authentication
    Methods" below.

   Authentication
    Run the following in a terminal, filling in XX_TOKEN_XX from the auth
    token above and XX_RT_URL_XX with the URL for your RT instance.

        curl -H 'Authorization: token XX_TOKEN_XX' 'XX_RT_URL_XX/REST/2.0/queues/all'

    This does an authenticated request (using the Authorization HTTP header
    with type token) for all of the queues you can see. You should see a
    response, typical of search results, like this:

        {
           "total" : 1,
           "count" : 1,
           "page" : 1,
           "pages" : 1,
           "per_page" : 20,
           "items" : [
              {
                 "type" : "queue",
                 "id" : "1",
                 "_url" : "XX_RT_URL_XX/REST/2.0/queue/1"
              }
           ]
        }

    This format is JSON, which is a format for which many programming
    languages provide libraries for parsing and generating.

    (If you instead see a response like {"message":"Unauthorized"} that
    indicates RT couldn't process your authentication token successfully;
    make sure the word "token" appears between "Authorization:" and the auth
    token that RT provided to you)

   Following Links
    You can request one of the provided _urls to get more information about
    that queue.

        curl -H 'Authorization: token XX_TOKEN_XX' 'XX_QUEUE_URL_XX'

    This will give a lot of information, like so:

        {
           "id" : 1,
           "Name" : "General",
           "Description" : "The default queue",
           "Lifecycle" : "default",
           ...
           "CustomFields" : {},
           "_hyperlinks" : [
              {
                 "id" : "1",
                 "ref" : "self",
                 "type" : "queue",
                 "_url" : "XX_RT_URL_XX/REST/2.0/queue/1"
              },
              {
                 "ref" : "history",
                 "_url" : "XX_RT_URL_XX/REST/2.0/queue/1/history"
              },
              {
                 "ref" : "create",
                 "type" : "ticket",
                 "_url" : "XX_RT_URL_XX/REST/2.0/ticket?Queue=1"
              }
           ],
        }

    Of particular note is the _hyperlinks key, which gives you a list of
    related resources to examine (following the
    <https://en.wikipedia.org/wiki/HATEOAS> principle). For example an entry
    with a ref of history lets you examine the transaction log for a record.
    You can implement your REST API client knowing that any other hypermedia
    link with a ref of history has the same meaning, regardless of whether
    it's the history of a queue, ticket, asset, etc.

    Another ref you'll see in _hyperlinks is create, with a type of ticket.
    This of course gives you the URL to create tickets *in this queue*.
    Importantly, if your user does *not* have the CreateTicket permission in
    this queue, then REST2 would simply not include this hyperlink in its
    response to your request. This allows you to dynamically adapt your
    client's behavior to its presence or absence, just like the web version
    of RT does.

   Creating Tickets
    Let's use the _url from the create hyperlink with type ticket.

    To create a ticket is a bit more involved, since it requires providing a
    different HTTP verb (POST instead of GET), a Content-Type header (to
    tell REST2 that your content is JSON instead of, say, XML), and the
    fields for your new ticket such as Subject. Here is the curl invocation,
    wrapped to multiple lines for readability.

        curl -X POST
             -H "Content-Type: application/json"
             -d '{ "Subject": "hello world" }'
             -H 'Authorization: token XX_TOKEN_XX'
                'XX_TICKET_CREATE_URL_XX'

    If successful, that will provide output like so:

        {
            "_url" : "XX_RT_URL_XX/REST/2.0/ticket/20",
            "type" : "ticket",
            "id"   : "20"
        }

    (REST2 also produces the status code of 201 Created with a Location
    header of the new ticket, which you may choose to use instead of the
    JSON response)

    We can fetch that _url to continue working with this newly-created
    ticket. Request the ticket like so (make sure to include the -i flag to
    see response's HTTP headers).

        curl -i -H 'Authorization: token XX_TOKEN_XX' 'XX_TICKET_URL_XX'

    You'll first see that there are many hyperlinks for tickets, including
    one for each Lifecycle action you can perform, history, comment,
    correspond, etc. Again these adapt to whether you have the appropriate
    permissions to do these actions.

    Additionally you'll see an ETag header for this record, which can be
    used for conflict avoidance (<https://en.wikipedia.org/wiki/HTTP_ETag>).
    We'll first try updating this ticket with an *invalid* ETag to see what
    happens.

   Updating Tickets
    For updating tickets we use the PUT verb, but otherwise it looks much
    like a ticket creation.

        curl -X PUT
             -H "Content-Type: application/json"
             -H "If-Match: invalid-etag"
             -d '{ "Subject": "trial update" }'
             -H 'Authorization: token XX_TOKEN_XX'
                'XX_TICKET_URL_XX'

    You'll get an error response like {"message":"Precondition Failed"} and
    a status code of 412. If you examine the ticket, you'll also see that
    its Subject was not changed. This is because the If-Match header advises
    the server to make changes *if and only if* the ticket's ETag matches
    what you provide. Since it differed, the server refused the request and
    made no changes.

    Now, try the same request by replacing the value "invalid-etag" in the
    If-Match request header with the real ETag you'd received when you
    requested the ticket previously. You'll then get a JSON response like:

        ["Ticket 1: Subject changed from 'hello world' to 'trial update'"]

    which is a list of messages meant for displaying to an end-user.

    If you GET the ticket again, you'll observe that the ETag header now has
    a different value, indicating that the ticket itself has changed. This
    means if you were to retry the PUT update with the previous (at the
    time, expected) ETag you would instead be rejected by the server with
    Precondition Failed.

    You can use ETag and If-Match headers to avoid race conditions such as
    two people updating a ticket at the same time. Depending on the
    sophistication of your client, you may be able to automatically retry
    the change by incorporating the changes made on the server (for example
    adding time worked can be automatically be recalculated).

    You may of course choose to ignore the ETag header and not provide
    If-Match in your requests; RT doesn't require its use.

   Replying/Commenting Tickets
    You can reply to or comment a ticket by POSTing to _url from the
    correspond or comment hyperlinks that were returned when fetching the
    ticket.

        curl -X POST
             -H "Content-Type: application/json"
             -d '{
                  "Subject"    : "response",
                  "Content"    : "What is your <em>issue</em>?",
                  "ContentType": "text/html",
                  "TimeTaken"  : "1"
                }'
             -H 'Authorization: token XX_TOKEN_XX'
                'XX_TICKET_URL_XX'/correspond

    Replying or commenting a ticket is quite similar to a ticket creation:
    you send a POST request, with data encoded in JSON. The difference lies
    in the properties of the JSON data object you can pass:

    Subject
        The subject of your response/comment, optional

    Content
        The content of your response/comment, mandatory unless there is a
        non empty Attachments property to add at least one attachment to the
        ticket (see "Add Attachments" section below).

    ContentType
        The MIME content type of your response/comment, typically text/plain
        or /text/html, mandatory unless there is a non empty Attachments
        property to add at least one attachment to the ticket (see "Add
        Attachments" section below).

    TimeTaken
        The time, in minutes, you've taken to work on your response/comment,
        optional.

    Status
        The new status (for example, "open", "rejected", etc.) to set the
        ticket to. The Status value must be a valid status based on the
        lifecycle of the ticket's current queue.

    CustomRoles
        A hash whose keys are custom role names and values are as described
        below:

        For a single-value custom role, the value must be a string
        representing an email address or user name; the custom role is set
        to the user with that email address or user name.

        For a multi-value custom role, the value can be a string
        representing an email address or user name, or can be an array of
        email addresses or user names; in either case, the members of the
        custom role are set to the corresponding users.

    CustomFields
        A hash similar to the CustomRoles hash, but whose keys are custom
        field names that apply to the Ticket; those fields are set to the
        supplied values.

    TxnCustomFields
        A hash similar to the CustomRoles hash, but whose keys are custom
        field names that apply to the Transaction; those fields are set to
        the supplied values.

   Add Attachments
    You can attach any binary or text file to your response or comment by
    specifying Attachements property in the JSON object, which should be a
    JSON array where each item represents a file you want to attach. Each
    item is a JSON object with the following properties:

    FileName
        The name of the file to attach to your response/comment, mandatory.

    FileType
        The MIME type of the file to attach to your response/comment,
        mandatory.

    FileContent
        The content, *encoded in MIME Base64* of the file to attach to your
        response/comment, mandatory.

    The reason why you should encode the content of any file to MIME Base64
    is that a JSON string value should be a sequence of zero or more Unicode
    characters. MIME Base64 is a binary-to-text encoding scheme widely used
    (for eg. by web browser) to send binary data when text data is required.
    Most popular language have MIME Base64 libraries that you can use to
    encode the content of your attached files (see MIME::Base64 for Perl).
    Note that even text files should be MIME Base64 encoded to be passed in
    the FileContent property.

    Here's a Perl example to send an image and a plain text file attached to
    a comment:

        #!/usr/bin/perl
        use strict;
        use warnings;

        use LWP::UserAgent;
        use JSON;
        use MIME::Base64;
        use Data::Dumper;

        my $url = 'http://rt.local/REST/2.0/ticket/1/comment';

        my $img_path = '/tmp/my_image.png';
        my $img_content;
        open my $img_fh, '<', $img_path or die "Cannot read $img_path: $!\n";
        {
            local $/;
            $img_content = <$img_fh>;
        }
        close $img_fh;
        $img_content = MIME::Base64::encode_base64($img_content);

        my $txt_path = '~/.bashrc';
        my $txt_content;
        open my $txt_fh, '<', glob($txt_path) or die "Cannot read $txt_path: $!\n";
        {
            local $/;
            $txt_content = <$txt_fh>;
        }
        close $txt_fh;
        $txt_content = MIME::Base64::encode_base64($txt_content);

        my $json = JSON->new->utf8;
        my $payload = {
            Content => '<p>I want <b>two</b> <em>attachments</em></p>',
            ContentType => 'text/html',
            Subject => 'Attachments in JSON Array',
            Attachments => [
                {
                    FileName => 'my_image.png',
                    FileType => 'image/png',
                    FileContent => $img_content,
                },
                {
                    FileName => '.bashrc',
                    FileType => 'text/plain',
                    FileContent => $txt_content,
                },
            ],
        };

        my $req = HTTP::Request->new(POST => $url);
        $req->header('Authorization' => 'token 6-66-66666666666666666666666666666666');
        $req->header('Content-Type'  => 'application/json' );
        $req->header('Accept'        => 'application/json' );
        $req->content($json->encode($payload));

        my $ua = LWP::UserAgent->new;
        my $res = $ua->request($req);
        print Dumper($json->decode($res->content)) . "\n";

    Encoding the content of attachments file in MIME Base64 has the drawback
    of adding some processing overhead and to increase the sent data size by
    around 33%. RT's REST2 API provides another way to attach any binary or
    text file to your response or comment by POSTing, instead of a JSON
    request, a multipart/form-data request. This kind of request is similar
    to what the browser sends when you add attachments in RT's reply or
    comment form. As its name suggests, a multipart/form-data request
    message contains a series of parts, each representing a form field. To
    reply to or comment a ticket, the request has to include a field named
    JSON, which, as previously, is a JSON object with Subject, Content,
    ContentType, TimeTaken properties. Files can then be attached by
    specifying a field named Attachments for each of them, with the content
    of the file as value and the appropriate MIME type.

    The curl invocation is quite straightforward:

        curl -X POST
             -H "Content-Type: multipart/form-data"
             -F 'JSON={
                        "Subject"    : "Attachments in multipart/form-data",
                        "Content"    : "<p>I want <b>two</b> <em>attachments</em></p>",
                        "ContentType": "text/html",
                        "TimeTaken"  : "1"
                      };type=application/json'
             -F 'Attachments=@/tmp/my_image.png;type=image/png'
             -F 'Attachments=@/tmp/.bashrc;type=text/plain'
             -H 'Authorization: token XX_TOKEN_XX'
                'XX_TICKET_URL_XX'/comment

   Summary
    RT's REST2 API provides the tools you need to build robust and dynamic
    integrations. Tools like ETag/If-Match allow you to avoid conflicts such
    as two people taking a ticket at the same time. Using JSON for all data
    interchange avoids problems caused by parsing text. Hypermedia links
    inform your client application of what the user has the ability to do.

    Careful readers will see that, other than our initial entry into the
    system, we did not *generate* any URLs. We only *followed* links, just
    like you do when browsing a website on your computer. We've better
    decoupled the client's implementation from the server's REST API.
    Additionally, this system lets you be informed of new capabilities in
    the form of additional hyperlinks.

    Using these tools and principles, REST2 will help you build rich,
    robust, and powerful integrations with the other applications and
    services that your team uses.

  Endpoints
    Currently provided endpoints under /REST/2.0/ are described below.
    Wherever possible please consider using _hyperlinks hypermedia controls
    available in response bodies rather than hardcoding URLs.

    For simplicity, the examples below omit the extra options to curl for
    SSL like --cacert.

   Tickets
        GET /tickets?query=<TicketSQL>
            search for tickets using TicketSQL

        GET /tickets?simple=1;query=<simple search query>
            search for tickets using simple search syntax

        # If there are multiple saved searches using the same description, the
        # behavior of "which saved search shall be selected" is undefined, use
        # id instead in this case.

        # If both search and other arguments like "query" are specified, the
        # latter takes higher precedence than the corresponding fields defined
        # in the given saved search.

        GET /tickets?search=<saved search id or description>
            search for tickets using saved search

        POST /tickets
            search for tickets with the 'search' or 'query' and optional 'simple' parameters 

        POST /ticket
            create a ticket; provide JSON content

        GET /ticket/:id
            retrieve a ticket

        PUT /ticket/:id
            update a ticket's metadata; provide JSON content

        DELETE /ticket/:id
            set status to deleted

        POST /ticket/:id/correspond
        POST /ticket/:id/comment
            add a reply or comment to the ticket

        GET /ticket/:id/history
            retrieve list of transactions for ticket

        POST /tickets/bulk
            create multiple tickets; provide JSON content(array of hashes)

        PUT /tickets/bulk
            update multiple tickets' metadata; provide JSON content(array of hashes)

        POST /tickets/bulk/correspond
        POST /tickets/bulk/comment
            add a reply or comment to multiple tickets; provide JSON content(array of hashes)

   Ticket Examples
    Below are some examples using the endpoints above.

        # Create a ticket, setting some custom fields and a custom role
        curl -X POST -H "Content-Type: application/json" -u 'root:password'
            -d '{ "Queue": "General", "Subject": "Create ticket test",
                "Requestor": "user1@example.com", "Cc": "user2@example.com",
                "CustomRoles": {"My Role": "staff1@example.com"},
                "Content": "Testing a create",
                "CustomFields": {"Severity": "Low"}}'
            'https://myrt.com/REST/2.0/ticket'

        # Update a ticket, with a custom field update
        curl -X PUT -H "Content-Type: application/json" -u 'root:password'
            -d '{ "Subject": "Update test", "CustomFields": {"Severity": "High"}}'
            'https://myrt.com/REST/2.0/ticket/6'

        # Correspond a ticket
        curl -X POST -H "Content-Type: application/json" -u 'root:password'
            -d '{ "Content": "Testing a correspondence", "ContentType": "text/plain" }'
            'https://myrt.com/REST/2.0/ticket/6/correspond'

        # Correspond a ticket with a transaction custom field
        curl -X POST -H "Content-Type: application/json" -u 'root:password'
            -d '{ "Content": "Testing a correspondence", "ContentType": "text/plain",
                  "TxnCustomFields": {"MyField": "custom field value"} }'
            'https://myrt.com/REST/2.0/ticket/6/correspond'

        # Comment on a ticket
        curl -X POST -H "Content-Type: text/plain" -u 'root:password'
            -d 'Testing a comment'
            'https://myrt.com/REST/2.0/ticket/6/comment'

        # Comment on a ticket with custom field update
        curl -X POST -H "Content-Type: application/json" -u 'root:password'
            -d '{ "Content": "Testing a comment", "ContentType": "text/plain", "CustomFields": {"Severity": "High"} }'
            'https://myrt.com/REST/2.0/ticket/6/comment'

        # Comment on a ticket with custom role update
        curl -X POST -H "Content-Type: application/json" -u 'root:password'
            -d '{ "Content": "Testing a comment", "ContentType": "text/plain", "CustomRoles": {"Manager": "manager@example.com"} }'
            'https://myrt.com/REST/2.0/ticket/6/comment'

        # Update many tickets at once with bulk by sending an array with ticket ids
        # Results are returned for each update in a JSON array with ticket ids and corresponding messages
        curl -X POST -H "Content-Type: application/json" -u 'root:password'
            -d '[{ "id": "20", "Content": "Testing a correspondence", "ContentType": "text/plain" },
                 { "id": "18", "Content": "Testing a correspondence", "ContentType": "text/plain", "Status":"resolved", "CustomRoles": {"Manager": "manager@example.com"}, "CustomFields": {"State": "New York"} }]'
            'https://myrt.com/REST/2.0/tickets/bulk/correspond'

        [["20","Correspondence added"],["18","Correspondence added","State New York added","Added manager@example.com as Manager for this ticket","Status changed from 'open' to 'resolved'"]]

   Transactions
        GET /transactions?query=<JSON>
        POST /transactions
            search for transactions using L</JSON searches> syntax

        GET /ticket/:id/history
        GET /queue/:id/history
        GET /queue/:name/history
        GET /asset/:id/history
        GET /user/:id/history
        GET /user/:name/history
        GET /group/:id/history
            get transactions for record

        GET /transaction/:id
            retrieve a transaction

   Attachments and Messages
        GET /attachments?query=<JSON>
        POST /attachments
            search for attachments using L</JSON searches> syntax

        GET /transaction/:id/attachments
            get attachments for transaction

        GET /attachment/:id
            retrieve an attachment

   Image and Binary Object Custom Field Values
        GET /download/cf/:id
            retrieve an image or a binary file as an object custom field value

   Queues
        GET /queues/all
            retrieve list of all queues you can see

        GET /queues?query=<JSON>
        POST /queues
            search for queues using L</JSON searches> syntax

        POST /queue
            create a queue; provide JSON content

        GET /queue/:id
        GET /queue/:name
            retrieve a queue by numeric id or name

        PUT /queue/:id
        PUT /queue/:name
            update a queue's metadata; provide JSON content

        DELETE /queue/:id
        DELETE /queue/:name
            disable queue

        GET /queue/:id/history
        GET /queue/:name/history
            retrieve list of transactions for queue

   Assets
        GET /assets?query=<JSON>
        POST /assets
            search for assets using L</JSON searches> syntax

        POST /asset
            create an asset; provide JSON content

        GET /asset/:id
            retrieve an asset

        PUT /asset/:id
            update an asset's metadata; provide JSON content

        DELETE /asset/:id
            set status to deleted

        GET /asset/:id/history
            retrieve list of transactions for asset

   Assets Examples
    Below are some examples using the endpoints above.

        # Create an Asset
        curl -X POST -H "Content-Type: application/json" -u 'root:password'
            -d '{"Name" : "Asset From Rest", "Catalog" : "General assets", "Content" : "Some content"}'
            'https://myrt.com/REST/2.0/asset'

        # Search Assets
        curl -X POST -H "Content-Type: application/json" -u 'root:password'
        -d '[{ "field" : "id", "operator" : ">=", "value" : 0 }]'
        'https://myrt.com/REST/2.0/assets'

   Catalogs
        GET /catalogs/all
            retrieve list of all catalogs you can see

        GET /catalogs?query=<JSON>
        POST /catalogs
            search for catalogs using L</JSON searches> syntax

        POST /catalog
            create a catalog; provide JSON content

        GET /catalog/:id
        GET /catalog/:name
            retrieve a catalog by numeric id or name

        PUT /catalog/:id
        PUT /catalog/:name
            update a catalog's metadata; provide JSON content

        DELETE /catalog/:id
        DELETE /catalog/:name
            disable catalog

   Users
        GET /users?query=<JSON>
        POST /users
            search for users using L</JSON searches> syntax

        POST /user
            create a user; provide JSON content

        GET /user/:id
        GET /user/:name
            retrieve a user by numeric id or username (including its memberships and whether it is disabled)

        PUT /user/:id
        PUT /user/:name
            update a user's metadata (including its Disabled status); provide JSON content

        DELETE /user/:id
        DELETE /user/:name
            disable user

        GET /user/:id/history
        GET /user/:name/history
            retrieve list of transactions for user

   Groups
        GET /groups?query=<JSON>
        POST /groups
            search for groups using L</JSON searches> syntax

        POST /group
            create a (user defined) group; provide JSON content

        GET /group/:id
            retrieve a group (including its members and whether it is disabled)

        PUT /group/:id
            update a groups's metadata (including its Disabled status); provide JSON content

        DELETE /group/:id
            disable group

        GET /group/:id/history
            retrieve list of transactions for group

   User Memberships
        GET /user/:id/groups
        GET /user/:name/groups
            retrieve list of groups which a user is a member of

        PUT /user/:id/groups
        PUT /user/:name/groups
            add a user to groups; provide a JSON array of groups ids

        DELETE /user/:id/group/:id
        DELETE /user/:name/group/:id
            remove a user from a group

        DELETE /user/:id/groups
        DELETE /user/:name/groups
            remove a user from all groups

   Group Members
        GET /group/:id/members
            retrieve list of direct members of a group

        GET /group/:id/members?recursively=1
            retrieve list of direct and recursive members of a group

        GET /group/:id/members?users=0
            retrieve list of direct group members of a group

        GET /group/:id/members?users=0&recursively=1
            retrieve list of direct and recursive group members of a group

        GET /group/:id/members?groups=0
            retrieve list of direct user members of a group

        GET /group/:id/members?groups=0&recursively=1
            retrieve list of direct and recursive user members of a group

        PUT /group/:id/members
            add members to a group; provide a JSON array of principal ids

        DELETE /group/:id/member/:id
            remove a member from a group

        DELETE /group/:id/members
            remove all members from a group

   Custom Fields
        GET /customfields?query=<JSON>
        POST /customfields
            search for custom fields using L</JSON searches> syntax

        POST /customfield
            create a customfield; provide JSON content

        GET /catalog/:id/customfields?query=<JSON>
        POST /catalog/:id/customfields
            search for custom fields attached to a catalog using L</JSON searches> syntax

        GET /class/:id/customfields?query=<JSON>
        POST /class/:id/customfields
            search for custom fields attached to a class using L</JSON searches> syntax

        GET /queue/:id/customfields?query=<JSON>
        POST /queue/:id/customfields
            search for custom fields attached to a queue using L</JSON searches> syntax

        GET /customfield/:id
            retrieve a custom field, with values if type is Select

        GET /customfield/:id?category=<category name>
            retrieve a custom field, with values filtered by category if type is Select

        PUT /customfield/:id
            update a custom field's metadata; provide JSON content

        DELETE /customfield/:id
            disable customfield

   Custom Field Values
        GET /customfield/:id/values?query=<JSON>
        POST /customfield/:id/values
            search for values of a custom field  using L</JSON searches> syntax

        POST /customfield/:id/value
            add a value to a custom field; provide JSON content

        GET /customfield/:id/value/:id
            retrieve a value of a custom field

        PUT /customfield/:id/value/:id
            update a value of a custom field; provide JSON content

        DELETE /customfield/:id/value/:id
            remove a value from a custom field

   Custom Roles
        GET /customroles?query=<JSON>
        POST /customroles
            search for custom roles using L</JSON searches> syntax

        GET /customrole/:id
            retrieve a custom role

   Saved Searches
        GET /searches?query=<JSON>
        POST /searches
            search for saved searches using L</JSON searches> syntax

        GET /search/:id
        GET /search/:description
            retrieve a saved search

   Miscellaneous
        GET /
            produces this documentation

        GET /rt
            produces system information

  JSON searches
    Some resources accept a basic JSON structure as the search conditions
    which specifies one or more fields to limit on (using specified
    operators and values). An example:

        curl -si -u user:pass https://rt.example.com/REST/2.0/queues -XPOST --data-binary '
            [
                { "field":    "Name",
                  "operator": "LIKE",
                  "value":    "Engineering" },

                { "field":    "Lifecycle",
                  "value":    "helpdesk" }
            ]
        '

    The JSON payload must be an array of hashes with the keys field and
    value and optionally operator.

    Results can be sorted by using multiple query parameter arguments
    orderby and order. Each orderby query parameter specify a field to be
    used for sorting results. If the request includes more than one orderby
    query parameter, results are sorted according to corresponding fields in
    the same order than they are specified. For instance, if you want to
    sort results according to creation date and then by id (in case of some
    items have the same creation date), your request should specify
    ?orderby=Created&orderby=id. By default, results are sorted in ascending
    order. To sort results in descending order, you should use order=DESC
    query parameter. Any other value for order query parameter will be
    treated as order=ASC, for ascending order. The order of the order query
    parameters should be the same as the orderby query parameters.
    Therefore, if you specify two fields to sort the results (with two
    orderby parameters) and you want to sort the second field by descending
    order, you should also explicitely specify order=ASC for the first
    field: orderby=Created&order=ASC&orderby=id&order=DESC. orderby and
    order query parameters are supported in both JSON and TicketSQL
    searches.

    The same field is specified more than one time to express more than one
    condition on this field. For example:

        [
            { "field":    "id",
              "operator": ">",
              "value":    $min },

            { "field":     "id",
              "operator": "<",
              "value":    $max }
        ]

    By default, RT will aggregate these conditions with an OR, except for
    when searching queues, where an AND is applied. If you want to search
    for multiple conditions on the same field aggregated with an AND (or an
    OR for queues), you can specify entry_aggregator keys in corresponding
    hashes:

        [
            { "field":    "id",
              "operator": ">",
              "value":    $min },

            { "field":             "id",
              "operator":         "<",
              "value":            $max,
              "entry_aggregator": "AND" }
        ]

    Results are returned in the format described below.

  Example of plural resources (collections)
    Resources which represent a collection of other resources use the
    following standard JSON format:

        {
           "count" : 20,
           "page" : 1,
           "pages" : 191,
           "per_page" : 20,
           "next_page" : "<collection path>?page=2"
           "total" : 3810,
           "items" : [
              { … },
              { … },
              …
           ]
        }

    Each item is nearly the same representation used when an individual
    resource is requested.

  Object Custom Field Values
    When creating (via POST) or updating (via PUT) a resource which has some
    custom fields attached to, you can specify the value(s) for these
    customfields in the CustomFields property of the JSON object parameter.
    The CustomFields property should be a JSON object, with each property
    being the custom field identifier or name. If the custom field can have
    only one value, you just have to speciy the value as JSON string for
    this custom field. If the customfield can have several value, you have
    to specify a JSON array of each value you want for this custom field.

        "CustomFields": {
            "XX_SINGLE_CF_ID_XX"   : "My Single Value",
            "XX_MULTI_VALUE_CF_ID": [
                "My First Value",
                "My Second Value"
            ]
        }

    Note that for a multi-value custom field, you have to specify all the
    values for this custom field. Therefore if the customfield for this
    resource already has some values, the existing values must be including
    in your update request if you want to keep them (and add some new
    values). Conversely, if you want to delete some existing values, do not
    include them in your update request (including only values you wan to
    keep). The following example deletes "My Second Value" from the previous
    example:

        "CustomFields": {
            "XX_MULTI_VALUE_CF_ID": [
                "My First Value"
            ]
        }

    To delete a single-value custom field, set its value to JSON null (undef
    in Perl):

        "CustomFields": {
            "XX_SINGLE_CF_ID_XX" : null
        }

    New values for Image and Binary custom fields can be set by specifying a
    JSON object as value for the custom field identifier or name with the
    following properties:

    FileName
        The name of the file to attach, mandatory.

    FileType
        The MIME type of the file to attach, mandatory.

    FileContent
        The content, *encoded in MIME Base64* of the file to attach,
        mandatory.

    The reason why you should encode the content of the image or binary file
    to MIME Base64 is that a JSON string value should be a sequence of zero
    or more Unicode characters. MIME Base64 is a binary-to-text encoding
    scheme widely used (for eg. by web browser) to send binary data when
    text data is required. Most popular language have MIME Base64 libraries
    that you can use to encode the content of your attached files (see
    MIME::Base64 for Perl). Note that even text files should be MIME Base64
    encoded to be passed in the FileContent property.

        "CustomFields": {
            "XX_SINGLE_IMAGE_OR_BINARY_CF_ID_XX"   : {
                "FileName"   : "image.png",
                "FileType"   : "image/png",
                "FileContent": "XX_BASE_64_STRING_XX"
            },
            "XX_MULTI_VALUE_IMAGE_OR_BINARY_CF_ID": [
                {
                    "FileName"   : "another_image.png",
                    "FileType"   : "image/png",
                    "FileContent": "XX_BASE_64_STRING_XX"
                },
                {
                    "FileName"   : "hello_world.txt",
                    "FileType"   : "text/plain",
                    "FileContent": "SGVsbG8gV29ybGQh"
                }
            ]
        }

    Encoding the content of image or binary files in MIME Base64 has the
    drawback of adding some processing overhead and to increase the sent
    data size by around 33%. RT's REST2 API provides another way to upload
    image or binary files as custom field alues by sending, instead of a
    JSON request, a multipart/form-data request. This kind of request is
    similar to what the browser sends when you upload a file in RT's ticket
    creation or update forms. As its name suggests, a multipart/form-data
    request message contains a series of parts, each representing a form
    field. To create or update a ticket with image or binary file, the
    multipart/form-data request has to include a field named JSON, which, as
    previously, is a JSON object with Queue, Subject, Content, ContentType,
    etc. properties. But instead of specifying each custom field value as a
    JSON object with FileName, FileType and FileContent properties, each
    custom field value should be a JSON object with UploadField. You can
    choose anything you want for this field name, except *Attachments*,
    which should be reserved for attaching files to a response or a comment
    to a ticket. Files can then be attached by specifying a field named as
    specified in the CustomFields property for each of them, with the
    content of the file as value and the appropriate MIME type.

    Here is an exemple of a curl invocation, wrapped to multiple lines for
    readability, to create a ticket with a multipart/request to upload some
    image or binary files as custom fields values.

        curl -X POST
             -H "Content-Type: multipart/form-data"
             -F 'JSON={
                        "Queue"      : "General",
                        "Subject"    : "hello world",
                        "Content"    : "That <em>damned</em> printer is out of order <b>again</b>!",
                        "ContentType": "text/html",
                        "CustomFields"  : {
                            "XX_SINGLE_IMAGE_OR_BINARY_CF_ID_XX"   => { "UploadField": "FILE_1",
                            "XX_MULTI_VALUE_IMAGE_OR_BINARY_CF_ID" => [ { "UploadField": "FILE_2" }, { "UploadField": "FILE_3" } ]
                        }
                      };type=application/json'
             -F 'FILE_1=@/tmp/image.png;type=image/png'
             -F 'FILE_2=@/tmp/another_image.png;type=image/png'
             -F 'FILE_3=@/etc/cups/cupsd.conf;type=text/plain'
             -H 'Authorization: token XX_TOKEN_XX'
                'XX_RT_URL_XX'/tickets

    If you want to delete some existing values from a multi-value image or
    binary custom field, you can just pass the existing filename as value
    for the custom field identifier or name, no need to upload again the
    content of the file. The following example will delete the text file and
    keep the image upload in previous example:

        "CustomFields": {
            "XX_MULTI_VALUE_IMAGE_OR_BINARY_CF_ID": [
                    "image.png"
            ]
        }

    To download an image or binary file which is the custom field value of a
    resource, you just have to make a GET request to the entry point
    returned for the corresponding custom field when fetching this resource,
    and it will return the content of the file as an octet string:

        curl -i -H 'Authorization: token XX_TOKEN_XX' 'XX_TICKET_URL_XX'

        {
            […]
            "XX_IMAGE_OR_BINARY_CF_ID_XX" : [
                {
                    "content_type" : "image/png",
                    "filename" : "image.png",
                    "_url" : "XX_RT_URL_XX/REST/2.0/download/cf/XX_IMAGE_OR_BINARY_OCFV_ID_XX"
                }
            ],
            […]
        },

        curl -i -H 'Authorization: token XX_TOKEN_XX'
            'XX_RT_URL_XX/REST/2.0/download/cf/XX_IMAGE_OR_BINARY_OCFV_ID_XX'
            > file.png

  Paging
    All plural resources (such as /tickets) require pagination, controlled
    by the query parameters page and per_page. The default page size is 20
    items, but it may be increased up to 100 (or decreased if desired). Page
    numbers start at 1. The number of pages is returned, and if there is a
    next or previous page, then the URL for that page is returned in the
    next_page and prev_page variables respectively. It is up to you to store
    the required JSON to pass with the following page request.

  Disabled items
    By default, only enabled objects are returned. To include disabled
    objects you can specify find_disabled_rows=1 as a query parameter.

  Fields
    When fetching search results you can include additional fields by adding
    a query parameter fields which is a comma seperated list of fields to
    include. You must use the camel case version of the name as included in
    the results for the actual item.

    You can use additional fields parameters to expand child blocks, for
    example (line wrapping inserted for readability):

        XX_RT_URL_XX/REST/2.0/tickets
          ?fields=Owner,Status,Created,Subject,Queue,CustomFields,Requestor,Cc,AdminCc,RT::CustomRole-1
          &fields[Queue]=Name,Description

    Says that in the result set for tickets, the extra fields for Owner,
    Status, Created, Subject, Queue, CustomFields, Requestor, Cc, AdminCc
    and CustomRoles should be included. But in addition, for the Queue
    block, also include Name and Description. The results would be similar
    to this (only one ticket is displayed in this example):

       "items" : [
          {
             "Subject" : "Sample Ticket",
             "id" : "2",
             "type" : "ticket",
             "Owner" : {
                "id" : "root",
                "_url" : "XX_RT_URL_XX/REST/2.0/user/root",
                "type" : "user"
             },
             "_url" : "XX_RT_URL_XX/REST/2.0/ticket/2",
             "Status" : "resolved",
             "Created" : "2018-06-29:10:25Z",
             "Queue" : {
                "id" : "1",
                "type" : "queue",
                "Name" : "General",
                "Description" : "The default queue",
                "_url" : "XX_RT_URL_XX/REST/2.0/queue/1"
             },
             "CustomFields" : [
                 {
                     "id" : "1",
                     "type" : "customfield",
                     "_url" : "XX_RT_URL_XX/REST/2.0/customfield/1",
                     "name" : "My Custom Field",
                     "values" : [
                         "CustomField value"
                     ]
                 }
             ],
             "Requestor" : [
                {
                   "id" : "root",
                   "type" : "user",
                   "_url" : "XX_RT_URL_XX/REST/2.0/user/root"
                }
             ],
             "Cc" : [
                {
                   "id" : "root",
                   "type" : "user",
                   "_url" : "XX_RT_URL_XX/REST/2.0/user/root"
                }
             ],
             "AdminCc" : [],
             "RT::CustomRole-1" : [
                {
                   "_url" : "XX_RT_URL_XX/REST/2.0/user/foo@example.com",
                   "type" : "user",
                   "id" : "foo@example.com"
                }
             ]
          }
          { … },
          …
       ],

    If the user performing the query doesn't have rights to view the record
    (or sub record), then the empty string will be returned.

    For single object URLs like /ticket/:id, as it already contains all the
    fields by default, parameter "fields" is not needed, but you can still
    use additional fields parameters to expand child blocks:

        XX_RT_URL_XX/REST/2.0/ticket/1?fields[Queue]=Name,Description

  Authentication Methods
    Authentication should always be done over HTTPS/SSL for security. You
    should only serve up the /REST/2.0/ endpoint over SSL.

   Basic Auth
    Authentication may use internal RT usernames and passwords, provided via
    HTTP Basic auth. Most HTTP libraries already have a way of providing
    basic auth credentials when making requests. Using curl, for example:

        curl -u 'username:password' /path/to/REST/2.0

   Token Auth
    You may use the RT::Authen::Token extension to authenticate to the REST
    2 API. Once you've acquired an authentication token in the web
    interface, specify the Authorization header with a value of "token" like
    so:

        curl -H 'Authorization: token …' /path/to/REST/2.0

    If the library or application you're using does not support specifying
    additional HTTP headers, you may also pass the authentication token as a
    query parameter like so:

        curl /path/to/REST/2.0?token=…

   Cookie Auth
    Finally, you may reuse an existing cookie from an ordinary web session
    to authenticate against REST2. This is primarily intended for
    interacting with REST2 via JavaScript in the browser. Other REST
    consumers are advised to use the alternatives above.

  Conditional requests (If-Modified-Since, If-Match)
    You can take advantage of the Last-Modified headers returned by most
    single resource endpoints. Add a If-Modified-Since header to your
    requests for the same resource, using the most recent Last-Modified
    value seen, and the API may respond with a 304 Not Modified. You can
    also use HEAD requests to check for updates without receiving the actual
    content when there is a newer version. You may also add an
    If-Unmodified-Since header to your updates to tell the server to refuse
    updates if the record had been changed since you last retrieved it.

    ETag, If-Match, and If-None-Match work similarly to Last-Modified,
    If-Modified-Since, and If-Unmodified-Since, except that they don't use a
    timestamp, which has its own set of tradeoffs. ETag is an opaque value,
    so it has no meaning to consumers (unlike timestamps). However,
    timestamps have the disadvantage of having a resolution of seconds, so
    two updates happening in the same second would produce incorrect
    results, whereas ETag does not suffer from that problem.

  Status codes
    The REST API uses the full range of HTTP status codes, and your client
    should handle them appropriately.

AUTHOR
    Best Practical Solutions, LLC <modules@bestpractical.com>

BUGS
    All bugs should be reported via email to
    bug-RT-Extension-REST2@rt.cpan.org
    <mailto:bug-RT-Extension-REST2@rt.cpan.org> or via the web at
    rt.cpan.org
    <http://rt.cpan.org/Public/Dist/Display.html?Name=RT-Extension-REST2>.

LICENSE AND COPYRIGHT
    This software is Copyright (c) 2015-2020 by Best Practical Solutions,
    LLC.

    This is free software, licensed under:

    The GNU General Public License, Version 2, June 1991