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 
}

[aleksei-averchenko-wise]

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

Sounds good! I thought of that initially but then decided to be clever and try and sneak the feature into existing calls to make adoption easier on my end. I'll redo it the way you suggested.