Working with GET and POST operations

/contacts/{contactId}/addresses:
  get:
    summary: "Returns the list of addresses for a given contact"
    description: "Returns the list of addresses for a given contact"
    operationId: getContactAddresses
    produces:
    - application/json
    parameters:
    - name: contactId
      in: path
      required: true
      type: string
    - name: limit
      in: query
      type: integer
      minimum: 1
      maximum: 100
    - name: offset
      in: query
      type: integer
      miniumum: 0
    responses:
      '200':
        description: "Successful creation"
        schema:
          $ref: "contact#/definitions/AddressList"

In the code snippet, notice the following:

• The defined operation is a GET operation.
• The value of operationId is getContactAddresses.
• The operation produces JSON objects.
• The operation defines three parameters, contactId, limit, offset. The three defined parameters become arguments to method getContactAddresses on API handler class.

The following Gosu fragments illustrates the necessary functions on the handler class for the defined GET operation.

public function getContactAddresses(contactId : String, limit : Integer, offset : Integer) : gw.pc.contact.v1_0.AddressList {
  
  var addresses = queryAddresses(contactId, limit, offset)
  var addressListJson = new gw.pc.contact.v1_0.AddressList()

  for (address : addresses) {
    addressListJson.addToAddresses(addressToJson(address))
  }
  return addressListJson
}
 
 
private function queryAddresses(contactId : String, limit : Integer, offset : Integer) : IQueryBeanResult<Address> {
  // Business logic
}
 
 
private function addressToJson(address : Address) : gw.pc.contact.v1_0.Address {
  var addressJson = new gw.pc.contact.v1_0.Address()
  addressJson.AddressLine1 = address.AddressLine1
  // More business logic
  return addressJson
}

In the code snippet, notice the following:

• The getContactAddresses method name matches the POST operationId value.
• The method arguments are parameters on the GET operation: contactId, limit, and offset.
• The method returns an address list as a JSON object.

The following Swagger fragment defines a typical POST operation on an example /contacts API endpoint.

/contacts:
  post:
    summary: "Create a contact"
    description: "Creates a new Contact entity and optionally sends it out to AddressBook"
    operationId: createContact
    consumes:
    - application/json
    produces:
    - application/json
    parameters:
    - name: body
      in: body
      required: true
      schema:
        $ref: "contact#/definitions/Contact"
    - name: updateAB
      in: query
      required: false
      type: boolean
    responses:
      '200':
        description: "Successful creation"
        schema:
          $ref: "contact#/definitions/Contact"

In the code snippet, notice the following:

• The defined operation is a POST operation.
• The value of operationId is createContact.
• The operation both produces and consumes JSON objects.
• The operation defines two parameters, body and updateAB, both of which become inputs to the handler class.

The following Gosu fragment illustrates the necessary functions on the handler class for the POST operation.

public function createContact(body : gw.pc.contact.v1_0.Contact, updateAB : Boolean) : 
       gw.pc.contact.v1_0.Contact {
  var contactEntity = createContact(body, updateAB != null && updateAB)
  return contactToJson(contactEntity)
}
 
private function createContact(contactJson : gw.pc.contact.v1_0.Contact, updateAB : Boolean) : Contact {
  // Actual business logic to construct and commit the entity
  var contactEntity : Contact
  Transaction.runWithNewBundle(bundle -> {
    contactEntity = new Contact(bundle)
    contactEntity.FirstName = contactJson.FirstName
    // More business logic
  })
  return contactEntity
}
 
private function contactToJson(contact : Contact) : gw.pc.contact.v1_0.Contact {
  // Mapping logic to turn the contact entity back into json
  var contactJson = new gw.pc.contact.v1_0.Contact()
  contactJson.FirstName = contact.FirstName
  contactJson.PublicId = contact.PublicId
  // More business logic
  return contactJson
}

In the code snippet, notice the following:

• The createContact method name matches the POST operationId value.
• The method arguments are parameters on the POST operation, body and updateAB.
• The method returns the new contact as a JSON object.