Add support for idempotency keys when creating tickets

[aleksei-averchenko-wise]

This change implements support for Zendesk's idempotency key
feature when creating tickets. I happen to need to use this feature myself :)

What's Changed

• Clients can now set an idempotency key on Ticket objects before creation
• The client automatically sends the Idempotency-Key header to the API
• The response is parsed to determine if this was a new ticket creation or a duplicate request
• New fields on Ticket:
  • getIdempotencyKey() / setIdempotencyKey(String) - the idempotency key
  • getIsIdempotencyHit() / setIsIdempotencyHit(Boolean) - whether this was a duplicate request

See the usage example in the README.

Caveat

The current implementation doesn't properly update idempotencyKey and isIdempotencyHit when creating a ticket via queueCreateTicketAsync. I don't know what the best approach would be here, any comments are welcome.

[PierreBtz]

Hey! Thanks for the contribution. I did not have time yet to look into it in details, but I wonder if we could maybe improve the architecture.

What you suggest is to add the idempotency fields as part of the Ticket model, which seems to mix two different concerns:

• the ticket model itself
• the idempotency feature, which is not really part of the Ticket model but a feature of the ticket creation flow

As a consequence of this choice, it means that stored tickets/serialized ticket will keep those fields which have no real value after the ticket creation flow is done (if I have a null what does that mean exactly?).

A potential approach to this problem would be to avoid changing the Ticket model (keep it aligned with the ZD one) and create a TicketResult or even a ZendeskResult<T> class if we want to be future proof that would contain both the model and the additional feature of the creation flow, so roughtly:

  public class CreateResult<T> {

    private final T entity;
    private final String idempotencyKey;
    private final boolean idempotencyHit;

// getters setters...
// we really need to bump from java 11 to have records...
}

Then you would keep the current createTicket methods and create new methods:

  public CreateResult<Ticket> createTicketIdempotent(Ticket ticket, String idempotencyKey) {
    return complete(createTicketIdempotentAsync(ticket, idempotencyKey));
  }

  public ListenableFuture<CreateResult<Ticket>> createTicketIdempotentAsync(
      Ticket ticket, String idempotencyKey) {
    // create the request
    // header addition
    // completion handler specific to idempotent feature
    // submit
  }

and so on...

Call for end user would look like:

  CreateResult<Ticket> result = zendesk.createTicketIdempotent(ticket, "key-123");
  Ticket created = result.getEntity();
  if (result.isIdempotencyHit()) { 
  // do stuff 
}