POST requests

There may be times when you have more parameters than a simple GET request can accommodate. Fortunately there are several resources that support converting these requests to POSTs.

There are two types of listings that support a POST: database requests and search requests, each with a different set of parameters and thus a different body format.

Resources that support POST

These endpoints support a POST using the database filter format.

• /authors (see Author resource)
• /titles (see Title resource)
• /works (see Work resource)
• /works/views/list-display
• /works/views/series-display

These endpoints support a POST using the search filter format.

• /search (see Search resource)

Constructing the POST request

POST body

The body should be a JSON object with elements made up of valid filter parameter names. For types that can be specified multiple times (e.g. isbn, catUri), the value should be an array; for types that take a single value (e.g. showCovers, onSaleFrom), the value should be that single value. Specifying NULL for a filter parameter is equivalent to omitting that parameter.

{
  "isbn": [9780399592805,9780399592812],
  "catUri": ["/fantasy","/history"],
  "showCovers": true,
  "onSaleFrom": "06/15/2018"
}

URL parameters

Not all of the parameters are moved into the JSON body. Anything that is listed in the Common Parameters documentation page should remain as GET parameters on the URL. So for example paging parameters such as start and rows should still be on the URL as well as sort and dir. And of course the api_key parameter that identifies your request to Mashery must always be present in the URL.

If a parameter is accepted by the endpoint but does not appear in the body format documentation below, then it should be included on the URL instead.

Specifying the content type

The POST should be made with a header specifying that the body is a JSON object.

Content-Type: application/json

Sample calls

Sample database listing

Here is a request that could be made just as easily as a GET request, but which demonstrates how to construct a valid POST request. We're selecting the first two works with the oldest on-sale dates from Bantam, Doubleday and Dell which are considered "new releases".

POST /PrhApi/domains/PRH.US/works?rows=2&sort=onsale&dir=asc&suppressLinks=true

Content-Type: application/json

{ "divisionCode":[12,13,14], "showNewReleases": true}    

{
  "status": "ok",
  "recordCount": 74,
  "startTimestamp": "2017-03-22T08:35Z",
  "endTimestamp": "2017-03-22T08:35Z",
  "timeTaken": 65,
  "data": {
    "works": [
      {
        "workId": 110271,
        "title": "DECISION AT DOONA",
        "author": "Anne McCaffrey",
        "onsale": "1975-03-12",
        "language": "E",
        "seoFriendlyUrl": "\/books\/110271\/decision-at-doona-by-anne-mccaffrey",
        "contribRoleCode": null,
        "contribRoleDesc": null,
        "seriesNumber": null,
        "_embeds": null,
        "_links": []
      },
      {
        "workId": 110316,
        "title": "THE SHIP WHO SANG",
        "author": "Anne McCaffrey",
        "onsale": "1976-01-12",
        "language": "E",
        "seoFriendlyUrl": "\/books\/110316\/the-ship-who-sang-by-anne-mccaffrey",
        "contribRoleCode": null,
        "contribRoleDesc": null,
        "seriesNumber": null,
        "_embeds": null,
        "_links": []
      }
    ],
    "_embeds": null,
    "_links": [...]
  },
  "error": null,
  "params": {
    "showNewReleases": true,
    "sort": "onsale",
    "dir": "asc",
    "domain": "PRH.US",
    "divisionCode": "12,13,14",
    "suppressLinks": true,
    "clientGroup": "Public",
    "rows": 2
  }
}

Sample search listing

Again, this would be a perfectly acceptable GET request based on the number of parameters that we're supplying, however it also serves to demonstrates how search facets can be supplied as a POST body.

POST /PrhApi/domains/PRH.US/search?q=persuasion&rows=1

Content-Type: application/json

{ "imprint": ["Modern Library","Bantam Classics"], "formatCode": ["EL"]}

{
  "status": "ok",
  "recordCount": 3,
  "startTimestamp": "2017-03-22T08:39Z",
  "endTimestamp": "2017-03-22T08:39Z",
  "timeTaken": 49,
  "data": {
    "results": [
      {
        "docType": "isbn",
        "id": "isbn-9780553904567-PRH.US",
        "key": "9780553904567",
        "name": "Persuasion",
        "score": 10.978655,
        "url": "\/books\/6399\/persuasion-by-jane-austen\/9780553904567",
        "domain": [
          "PRH.US"
        ],
        "title": null,
        "description": [
          "<p>Of all Jane Austen&rsquo;s great and delightful novels,..."],
        "author": [
          "1044|Jane Austen"
        ],
        "authorFirst": null,
        "authorLast": null,
        "photoCredit": null,
        "onTour": null,
        "seriesAuthor": null,
        "seriesIsbn": null,
        "seriesCount": null,
        "_links": [...],
        "_embeds": null
      }
    ],
    "correctlySpelled": true,
    "suggestions": {
      
    },
    "facets": [
      {
        "name": "companyCode",
        "values": {
          
        }
      },
      {
        "name": "bestseller",
        "values": {
          "false": 3
        }
      },
      {
        "name": "award",
        "values": {
          
        }
      },
      {
        "name": "eventCityState",
        "values": {
          
        }
      },
      {
        "name": "categoryLabel",
        "values": {
          "Classics": 3,
          "Fiction": 3,
          "Romance": 2
        }
      },
      {
        "name": "formatCode",
        "values": {
          "EL": 3
        }
      },
      {
        "name": "newRelease",
        "values": {
          "false": 3
        }
      },
      {
        "name": "author",
        "values": {
          "1044|Jane Austen": 3
        }
      },
      {
        "name": "subformat",
        "values": {
          "001": 3
        }
      },
      {
        "name": "comingSoon",
        "values": {
          "false": 3
        }
      },
      {
        "name": "awardWinner",
        "values": {
          "false": 3
        }
      },
      {
        "name": "series",
        "values": {
          
        }
      },
      {
        "name": "authorLastInitial",
        "values": {
          
        }
      },
      {
        "name": "docType",
        "values": {
          "isbn": 3
        }
      },
      {
        "name": "imprint",
        "values": {
          "Bantam Classics": 1,
          "Modern Library": 2
        }
      },
      {
        "name": "ageRange",
        "values": {
          
        }
      },
      {
        "name": "format",
        "values": {
          "Ebook": 3
        }
      },
      {
        "name": "division",
        "values": {
          "Bantam Dell": 1,
          "Random House Group": 2
        }
      }
    ],
    "_links": [...],
    "_embeds": null
  },
  "error": null,
  "params": {
    "imprint": "Modern Library,Bantam Classics",
    "q": "persuasion",
    "domain": "PRH.US",
    "clientGroup": "Public",
    "rows": 1
  }
}

POST body formats

All POST requests take a single JSON object that is in one of two formats: the database filter format or the search filter format. Each format is a simple hash where the parameter name is the key and the parameter value is the hash value. In cases where the parameter can be specified multiple times, the JSON object will expect an array type.

Database filter format

The documentation of this format is taken directly from the source of the Java class FilterWorks.

    List<Long> workId;
    List<Long> isbn;
    List<Long> authorId;
    List<String> divisionCode;
    List<String> imprintCode;
    List<String> seriesCode;
    List<String> format;
    List<String> formatFamily;
    List<Long> eventId;
    List<Long> catId;
    List<String> catUri;
    List<String> catSetId;
    List<Integer> titleWebLinkAttr;
    List<Integer> authorWebLinkAttr;
    List<String> contribRoleCode;
    List<String> consumerImprint;
    List<String> language;
    List<Integer> catSeq;
    List<String> productLine;
    List<String> productType;
    List<String> ageRange;
    List<String> salesRestriction;
    List<String> saleStatus;
    List<String> subFormat;
    List<String> subSeries;
    List<String> propertyName;
    List<String> subtitlePrefix;
    List<Integer> seriesNumber;

    List<Long> ignoreIsbn;
    List<Long> ignoreWork;
    List<Long> ignoreAuthor;
    List<String> ignoreFormatFamily;
    List<String> ignoreFormatCode;
    List<String> ignoreCatUri;
    List<String> ignoreSeries;
    List<String> ignoreContribRole;
    List<String> ignoreSubFormat;
    List<String> ignoreProductLine;
    List<String> ignoreProductType;
    List<String> ignoreDivisionCode;
    List<String> ignoreSaleStatus;
    List<String> ignoreSalesRestriction;

    Boolean showAwards;
    Boolean showBestsellers;
    Boolean showNewReleases;
    Boolean showComingSoon;
    Boolean showPublishedBooks;
    Boolean showCovers;
    Boolean hideBooksWithNoCover;
    Boolean showReadingGuides;
    Boolean showTeachersGuides;
    Boolean showBoxBundles;
    Boolean showFlapCopy;
    Boolean showExcerpt;
    Boolean showNoTitleBlock;
    Boolean hasSeriesNumber;

    Integer minInPrint;
    Integer minPrintScore;
    Integer awardMaxSeq;
    Integer ageRangeMin;
    Integer ageRangeMax;

    Date onSaleFrom;
    Date onSaleTo;
    Date workOnSaleFrom;
    Date workOnSaleTo;

    String preferLanguage;
    SiteFilter siteFilter;

Search filter format

The documentation of this format is taken directly from the source of the Java class FilterSearch. 

    List<ApiDocType> docType;
    List<ApiDocType> docTypeExclude;
    List<String> ageRange;
    List<String> award;
    List<String> categoryId;
    List<String> categoryLabel;
    List<String> division;
    List<String> format;
    List<String> subformat;
    List<String> formatCode;
    List<String> imprint;
    List<String> series;
    Boolean bestseller;
    Boolean awardWinner;
    Boolean comingSoon;
    Boolean newRelease;
    Boolean forthcomingRelease;

    // author facets
    List<String> authorLastInitial;
    List<String> contribRoleCode;
    List<String> companyCode;

    // event facets
    List<String> author;
    Date from;
    Date to;
    List<String> eventCityState;
    String zip;
    Integer within;

    // series facets
    Integer seriesCountMin;

    // meta params
    String fieldWeighting;
    String phraseWeighting;
    Integer exactMatchWeighting;