Swagger docs updates

[ylembachar]

Shutter Service API Documentation Updates

Things to Do

• Create an address/private key that will be used for the API.
• Store the generated address/private key in 1Password.
• Update the Swagger documentation to reflect the new address.

---

Swagger Documentation Updates

1. Intro

1.1. Change intro to:

The Shutter Service API is an API on top of the Shutter Service that allows users to easily use Shutter's encryption and decryption features. Users can:

• register identities with a decryption timestamp
• retrieve the encryption data for a certain identity
• retrieve the decryption key once the decryption timestamp is reached
• decrypt encrypted commitments

1.2. Remove the crypto added keyword on top of the list of endpoints

---

2. Endpoints

2.1. register_identity

• Title: Change to: Allows clients to register an identity.
• Description: Update to:
  Allows clients to register an identity used for encryption and specify a unix decryption timestamp. When the decryption timestamp is reached, the decryption key is available for decryption.
• Parameters: Change to:
  • decryption timestamp (integer)
  • identityPrefix (string)
• Parameter Description: Update to:
  Decryption timestamp and identity prefix required for the registration. Please note that any registered identity via this endpoint will use the API address TBD for identity computation.

---

2.2. get_decryption_key

• Title: Change to: Allows clients to retrieve a decryption key.
• Description: Update to:
  Retrieves a decryption key for a given registered identity once the timestamp is reached. Decryption key is returned with a 0X prefix which should be removed when decrypting using the decrypt function (add link here).

---

2.3. get_data_for_encryption

• Title: Change to: Provides the necessary data for encryption.
• Description: Update to:
  Retrieves the necessary data to encrypt a commitment.
• Address Description: Update to:
  Ethereum address used to compute the identity. Users registering identities directly through the registration contract should use the address of the account used during registration. Users using the API to register their identities should use the API address TBD.

---

2.4. decrypt_commitment

• Title: Change to: Allows clients to decrypt an encrypted commitment.
• Description: Update to:
  Allows clients to easily decrypt their encrypted commitment provided that they have registered the corresponding identity. The decryption timestamp should be in the past for the commitment to be decrypted successfully.
• Identity Description: Update to:
  Identity used for registration and commitment encryption.
• Parameter encryptedCommitment: Update to:
  The client encrypted commitment. This is a string that was encrypted using the above identity.

---

3. Error Example Values

• Correct the example values for errors.
  Issue: Errors currently show statusCode: 0 and incorrect descriptions/metadata.
  Fix: Update all endpoints to show accurate example error values.

---

4. 400 Errors

• Update descriptions for 400 errors:
  Change Invalid Register identity request to Invalid parameters for all endpoints.

---

5. README

• Add a README.md with instructions on how to generate the Swagger documentation after an update.