Users

This is an object representing a user. You can retrieve it to see properties likes its name or address.

Create

Required Attributes

• email
• password
• givenName
• familyName

Example Request

POST /users HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "users",
    "attributes": {
      "email": "new-user@example-domain.com",
      "password": "Sh@Z@M1",
      "honorificPrefix": "Mr.",
      "givenName": "Bob",
      "additionalName": "James",
      "familyName": "Smith",
      "honorificSuffix": "Jr.",
      "address": {
        "streetAddress": "123 Main St.",
        "unitNumber": "Appt 4B",
        "addressLocality": "Chicago",
        /*
         * NOTE: Two characters MAX when country is US or CA.  Otherwise, use
         * the full region name.
         */
        "addressRegion": "IL",
        "addressCountry": "US",
        "postalCode": "60610"
      },
      "circulationNumber": "WS5312",
      "internalNotes": "Our most prized customer!",
      "jobTitle": "Sr. Vice President",
      "worksFor": {
        "legalName": "ePublishing, Inc.",
        "telephone": "555-555-1234"
      },
      "telephone": "555-555-9876",
      "cellNumber": "555-555-4567",
      "faxNumber": "555-555-9192",
      "demographics": {
        "recommendations": ["always"]
      },
      "newsletters": {
        "add": ["1", "2"]
      }
    }
  }
}

Example Response

HTTP/1.1 201 Created
Location: https://api.epublishing.com/users/42
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "users",
    "id": "42",
    "attributes": {
      "email": "new-user@example-domain.com",
      "honorificPrefix": "Mr.",
      "givenName": "Bob",
      "additionalName": "James",
      "familyName": "Smith",
      "honorificSuffix": "Jr.",
      "address": {
        "streetAddress": "123 Main St.",
        "unitNumber": "Appt 4B",
        "addressLocality": "Chicago",
        "addressRegion": "IL",
        "addressCountry": "US",
        "postalCode": "60610"
      },
      "circulationNumber": "WS5312",
      "internalNotes": "Our most prized customer!",
      "jobTitle": "Sr. Vice President",
      "worksFor": {
        "legalName": "ePublishing, Inc.",
        "telephone": "555-555-1234"
      },
      "telephone": "555-555-9876",
      "cellNumber": "555-555-4567",
      "faxNumber": "555-555-9192",
      "demographics": {
        "recommendations": ["always"]
      },
      "newsletters": ["1", "2"]
    },
    "links": {
      "self": "https://api.epublishing.com/users/42"
    }
  }
}

Errors

400 Bad Request

Sending invalid JSON results in a 400 Bad Request response:

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.api+json

{
  "errors": [
    {
      "title": "Problems parsing JSON"
    }
  ]
}

Sending the wrong type of JSON values results in a 400 Bad Request response:

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.api+json

{
  "errors": [
    {
      "title": "Body must be a JSON object"
    }
  ]
}

422 Unprocessable Entity

Sending invalid fields results in a 422 Unprocessable Entity response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/vnd.api+json

{
  "errors": [
    {
      "detail": "can't be blank",
      "source": {
        "pointer": "/data/attributes/familyName"
      }
    },
    {
      "detail": "must be a valid email address",
      "source": {
        "pointer": "/data/attributes/email"
      }
    }
  ]
}

Retrieving all Users

You can retrieve all Users present in the database, 100 per page. Results are ordered by ePublishing ID ascending.

Example Request

GET /users HTTP/1.1
Accept: application/vnd.api+json

GET /users?page[number]=2 HTTP/1.1
Accept: application/vnd.api+json

Example Response

HTTP/1.1 200 Success
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "https://api.epublishing.com/users",
    "next": "https://api.epublishing.com/users?page[number]=2",
    "first: "https://api.epublishing.com/users?page[number]=1"
  },
  "data": [
    {
      "type": "users",
      "id": "42",
      "attributes": {
        "email": "new-user@example-domain.com",
        "honorificPrefix": "Mr.",
        "givenName": "Bob",
        "additionalName": "James",
        "familyName": "Smith",
        "honorificSuffix": "Jr.",
        "address": {
          "streetAddress": "123 Main St.",
          "unitNumber": "Appt 4B",
          "addressLocality": "Chicago",
          "addressRegion": "IL",
          "addressCountry": "US",
          "postalCode": "60610"
        },
        "circulationNumber": "WS5312",
        "internalNotes": "Our most prized customer!",
        "jobTitle": "Sr. Vice President",
        "worksFor": {
          "legalName": "ePublishing, Inc.",
          "telephone": "555-555-1234"
        },
        "telephone": "555-555-9876",
        "cellNumber": "555-555-4567",
        "faxNumber": "555-555-9192",
        "demographics": {
          "recommendations": ["always"]
        },
        "newsletters": ["1", "2"]
      }
    },
    {...},
    {...}
  ]
}

Filtering

You can search for users by either email or circulationNumber. These are query parameters.

Example Request

GET /users?filter[email]=example-domain.com HTTP/1.1
Accept: application/vnd.api+json

Example Response

HTTP/1.1 200 Success
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "https://api.epublishing.com/users",
    "next": "https://api.epublishing.com/users?filter[email]=example-domain.com&page=2",
    "first: "https://api.epublishing.com/users?filter[email]=example-domain.com&page=1"
  },
  "data": [
    {
      "type": "users",
      "id": "42",
      "attributes": {
        "email": "new-user@example-domain.com",
        "honorificPrefix": "Mr.",
        "givenName": "Bob",
        "additionalName": "James",
        "familyName": "Smith",
        "honorificSuffix": "Jr.",
        "address": {
          "streetAddress": "123 Main St.",
          "unitNumber": "Appt 4B",
          "addressLocality": "Chicago",
          "addressRegion": "IL",
          "addressCountry": "US",
          "postalCode": "60610"
        },
        "circulationNumber": "WS5312",
        "internalNotes": "Our most prized customer!",
        "jobTitle": "Sr. Vice President",
        "worksFor": {
          "legalName": "ePublishing, Inc.",
          "telephone": "555-555-1234"
        },
        "telephone": "555-555-9876",
        "cellNumber": "555-555-4567",
        "faxNumber": "555-555-9192",
        "demographics": {
          "recommendations": ["always"]
        }
      }
    },
    {...},
    {...}
  ]
}

Updating

Example Request

PUT /users/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "users",
    "id": "1",
    "attributes": {
      "circulationNumber": "12345",
      "demographics": {
        "recommendations": ["always"]
      },
      "newsletters": {
        "add": ["1", "2"],
        "remove": ["3", "4"],
      }
    }
  }
}

Example Response

HTTP/1.1 204 No Content
Content-Type: application/vnd.api+json

Errors

Any validation failures during the update return the same type of error response as a "create" action.