OZP_agencyAPI.md

#API Object: marketplace.Agency

##Definition Use the /agency API to create, update, read or delete an agency in the system.

##Resource Information## The following properties appear in the Agency JSON:

Parameter	Description
id	The numerical ID associated with the agency object.
shortName	The abbreviation used to identify the agency on listings' short and detailed views.
title	The name of the agency.

##Request URL###

https://localhost:8443/marketplace/api/agency

This placeholder URL will vary depending upon your deployment. Be mindful that https://localhost:8443/marketplace is an example "base/context/domain" where your WAR is deployed.

##Request Methods POST, PUT, GET, DELETE
Each method will be explained in the following sections:

###POST#### Use this call to create an agency in the system.

#####Request https://localhost:8443/marketplace/api/agency

{  
    "title":"Test Organization",
    "shortName":"TORG"
}

#####Response Code: 201

#####Response

{
  "id": 1,
  "shortName": "TORG",
  "title": "Test Organization",
  "_links": {
    "self": {
      "href": "https://localhost:8443/marketplace/api/agency/1"
    }
  }
}

#####Requirements none

###PUT Use this call to update an agency in the system. #####Request https://localhost:8443/marketplace/api/agency/{id}

{  
    "id":208,
    "title":"Updated Agency",
    "shortName":"sName"
}

#####Response Code: 200

#####Response

{
  "id": 1,
  "shortName": "TORG",
  "title": "Test Organization",
  "_links": {
    "self": {
      "href": "https://localhost:8443/marketplace/api/agency/1"
    }
  }
}

#####Requirements none

###GET Use this call to read or view an agency or all the agencies in the system. #####Request If you want to see a list of all the agencies in the system, enter: https://localhost:8443/marketplace/api/agency/

However, to view metadata about only one agency, enter: https://localhost:8443/marketplace/api/agency/{id}

Marketplace returns the representation of the agency that matches the{id}, as shown in the Response for one agency id.

#####Response Code: 200

#####Response for one agency id

{
   "id":194,
   "shortName":"sName",
   "title":"123456",
   "_links":
   {
      "self":
      {
         "href":"https://localhost:8443/marketplace/api/agency/194"
      }
   }
}

#####Requirements none #####Optional Parameters If you want to limit the responses, for example, only return 5, you can do so using Optional Parameters which are included in the code as @QueryParam:

offset--an integer offset
Example: https://localhost:8443/marketplace/api/agency?offset=5

max--maximum number of agency ids your call will return Example: https://localhost:8443/marketplace/api/agency?max=5

###DELETE Use this call to remove an agency from the system. #####Requirements https://localhost:8443/marketplace/api/agency/{id}

#####Response Code: 204

#####Response no content

#####Requirements none

###Possible Errors

This table lists common errors. Other errors may occur but these are the most likely:

Error Code	Error	Troubleshooting
400	Agency cannot be deleted.	See if it is associated with a listing. If any listing is assigned to an agency, you cannot delete that agency.
403	User cannot create, edit, delete an agency.	Only administrators can create, edit, delete agencies.
400	Agency cannot be created or updated.	The agency must include all required fields.
400	Agency must have a unique name.	If the agency name is not unique, a validation error occurs when you try to save.