How To Write the Minimum ANS for a Viable Image Document

The ANS schema has a lot of specific keys and details that can vary widely between ANS content types. When planning to write ANS for a migration using the Arc XP APIs, which fields are the most necessary ones? Let’s narrow the focus, and pay attention to only the minimum selection of all the possible ANS fields necessary to create one kind of Arc XP content. What ANS fields are the most necessary ones when creating an Arc XP image that will be created programmatically using the Photo Center API?

In this article we will discuss what is the minimum ANS that will result in a viable Arc XP image. There will still be other useful image ANS fields that are not included in this discussion. After reviewing this article, you will be equipped with a solid image ANS starting point.

About API Testing Tools

Some of the Photo Center API requests discussed below demonstrate posting JSON in a multipart/form-data request. API tools can handle the content type declaration of a form field’s value very differently when the request is multipart/form-data. If not correctly handled, the endpoints will error:

{
  "error": "Unsupported Media",
  "message": "Content type 'application/octet-stream' not supported",
  "status": 415
}

Insomnia	When in the form field interface, add the ANS JSON using the multi-line text interface, and set the Editor Syntax choice in this screen to JSON. The default of this choice may be set to String.
Postman	When in the Body panel in the form data interface, make sure you fill in key, value and content type fields. If the content type field remains on the auto default, the JSON you place in the value field will likely be sent through as a string. Set the content type field of the ans form key to application/json. The content type of the request itself will still be multipart/form-data, which you can verify on the Headers panel.
Terminal	Manually add a content type declaration to the bottom of the curl, directly after the ANS JSON, after the final curly brace: form 'ans={...}; type=application/json'

Photo Center API Image Creation Endpoints

This is the absolute minimum ANS needed to create a photo.

{
  "version": "0.10.7",
  "type": "image",
  "owner": {
    "id": "sandbox.arctesting1"
  },
  "additional_properties": {
    "originalUrl": "https://images.unsplash.com/photo-1654452698901-cf57845dd7a7"
  }
}

When creating a photo through the API using ANS, the additional_properties.originalUrl key must contain a fully qualified, reachable url. Photo Center will access the image at additional_properties.originalUrl and download it from that location. If you can enter the url in a browser and an image displays, this is a good test to show that Photo Center should be able to access and download it too.

When Photo Center downloads the image at the url it will discover the image’s ITPC metadata. Photo Center will apply metadata from the downloaded image to associated fields in the resulting ANS, unless there is already the same ANS key in the incoming JSON payload; for example the ANS fields width and height are filled in this way.

Below,additional_properties.originalUrl has been replaced with a relative path, followed by the ANS error that would be generated.

Post Image ANS, Passing a Specific Arc ID

Photo Center API Endpoint /v2/photos to Upload A Photo Either By ANS Or By File, With A Specific ID.

There are two ways to make use this API endpoint; one where the request sends a Content-Type header of application/json and one where the request sends a Content-Type header of multipart/form-data

With header Content-Type: application/json

• The headers include Content-Type: application/json
• The ANS is the JSON payload. Some API utilities can turn a JSON object into a series of strings. A string object in the payload instead of a JSON object will cause the request to fail.
• The ANS must include an _id key
• The endpoint’s last path segment is the _id value
• The ANS must contain an additional_properties.originalUrl key and the value of that url must be accessible by a browser

curl --request POST \
  --url https://api.sandbox.arctesting1.arcpublishing.com/photo/api/v2/photos/TESTTESTNAWNYEUP2VOBDINLPI \
  --header 'Authorization: <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "_id": "TESTTESTNAWNYEUP2VOBDINLPI",
    "version": "0.10.7",
    "type": "image",
    "owner": {
        "id": "sandbox.arctesting1"
    },
    "additional_properties": {
        "originalUrl": "https://images.unsplash.com/photo-1654452698901-cf57845dd7a7"
   }
}'

With header Content-Type: multipart/form

• The headers include Content-Type: multipart/form-data
• The form field is named ans, lower cased
• The ans field value must carry a JSON payload. Some API utilities can turn a JSON object into a series of strings. A string object in the payload instead of a JSON object will cause the request to fail
• The JSON may be inline or included from an external file
• The ANS must include an _id key
• The endpoint’s last path segment is the _id value
• The ANS must contain an additional_properties.originalUrl key and the value of that url must be accessible by a browser

curl --request POST \
  --url https://api.sandbox.arctesting1.arcpublishing.com/photo/api/v2/photos/TESTTESTNAWNYEUP2VOBDINLPI \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'ans={
    "version": "0.10.7",
    "type": "image",
    "_id": "TESTTESTNAWNYEUP2VOBDINLPI",
    "owner": {
        "id": "sandbox.arctesting1"
    },
    "additional_properties": {
        "originalUrl": "https://images.unsplash.com/photo-1654452698901-cf57845dd7a7"
    }
};type=application/json'

...or instead include the ans from a file … ANS id is included in the JSON

  --form ans=@\path_to_json\ans_with_ID.json

Post Image ANS, Allowing Arc to Create the Arc ID Automatically

Photo Center API Endpoint: /v2/photos to Upload A Photo Either By ANS Or By File, With A Specific ID.

The ANS POSTed to this endpoint must not contain an Arc ID field. If an Arc ID is included, this endpoint will fail. The payload returned from a successful POST to this endpoint will contain the fully created image ANS, including a generated Arc ID. The API request to this endpoint must conform to these very specific criteria:

• The headers include Content-Type: multipart/form
• The form field is named ans, lower cased.
• The ans field value must carry a JSON payload. Some API utilities can turn a JSON object into a series of strings. A string object in the payload instead of a JSON object will cause the request to fail.
• The JSON may be inline or included from an external file.
• The ANS must not contain an _id key.
• The ANS must contain an additional_properties.originalUrl key and the value of that url must be accessible by a browser.

curl --request POST \
  --url https://api.sandbox.arctesting1.arcpublishing.com/photo/api/v2/photos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'ans={
    "version": "0.10.7",
    "type": "image",
    "owner": {
        "id": "sandbox.arctesting1"
    },
    "additional_properties": {
        "originalUrl": "https://images.unsplash.com/photo-1654452698901-cf57845dd7a7"
   }
};type=application/json'

  ...or instead include the ans from a file ...no ANS id in the JSON

  --form ans=@\path_to_json\NO_ansid_.json

Upload a binary image file

Both versions of the API endpoint allow you to POST an image file directly to Photo Center. When sending a binary file, do not include ANS in the POST at all. All ANS will be created by Photo Center, populated from the image IPTC metadata. The image binary must be on the same machine as the process that is making the request.

The request parameters that are necessary to send an image file through the API are:

• The headers include Content-Type: multipart/form
• The file parameter is named file
• Include an Arc ID as a path segment in the url to set the _id value of the imported image, or this may be left off and the Arc ID will be automatically generated

curl --request POST \
  --url https://api.sandbox.arctesting1.arcpublishing.com/photo/api/v2/photos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@/Users/mycomputer/Downloads/dan-freeman-WHPsxhB4mWQ-unsplash.jpg

   ...or this curl url if you have created the ans id to use for the image...

  --url https://api.sandbox.arctesting1.arcpublishing.com/photo/api/v2/photos/TESTTESTNAWNYEUP2VOBDINLPI

Additional Useful ANS Fields

The absolute minimum ANS will create an image in photo center, which will be populated with the IPTC metadata that is recognized by Arc XP. You may want to set Arc XP fields like the image caption or the file name explicitly. You can do that by including them in the ANS that you send into Arc XP. We will go over common ANS elements that build out the image ANS that simply creates an image into ANS that creates an image with some useful metadata.

Photo Center will default the image’s file name to the last string element of the url. If the url doesn’t include a file extension, then neither will the image’s file name. Images that don’t have a file name that ends in an extension may encounter difficulties when rendered in a browser.

Add additional_properties.originalName to the ANS to set a specific file name for the image. If this field is not in the ANS, Photo Center will parse a substitute name off of the end of the additional_properties.originalUrl field.

{
  "additional_properties": {
    "originalName": "photo-of-an-object.jpg"
  }
}

Captions, subtitles or headlines, and alt text are recorded in similarly named ANS fields. In the Photo Center UI the “Headline” field is populated from the ANS subtitle field.

{
  "caption": "i am a caption",
  "subtitle": "i am a headline",
  "alt_text": "i am image alt text",
}

Add publish_date and display_date to the ANS to set date values on the image. The dates must be in UTC timezone and use the formatYYYY-MM-DDThh:mm:ss.microsecondsZ

{
  "display_date": "2021-03-03T00:00:00.000Z",
  "publish_date": "2021-03-03T00:00:00.000Z",
}

Add additional_properties.expiration_date to the ANS in order to trigger the image to expire at a future date.Read herefor more information on how the expiration_date field controls when and under what conditions an image is deleted from Photo Center.

{
  "additional_properties": {
    "expiration_date": "2022-06-19T00:00:00Z"
  }
}

Add additional_properties.published: true and the image will be published when the ANS is posted.

{
  "additional_properties": {
    "published": true
  }
}

Image ANS Example

These additions lead us to this functional ANS that will create an image that contains some useful metadata and will be good for use in Arc XP documents.

{
    "_id": "TESTTESTNAWNYEUP2VOBDINLPI",
    "version": "0.10.7",
    "type": "image",
    "owner": {
        "id": "sandbox.arctesting1"
    },
    "display_date": "2021-03-03T00:00:00.000Z",
    "publish_date": "2021-03-03T00:00:00.000Z",
    "caption": "i am a caption",
    "subtitle": "i am a headline",
    "alt_text": "i am image alt text",
    "additional_properties": {
        "originalUrl": "https://images.unsplash.com/photo-1654452698901-cf57845dd7a7",
        "originalName": "photo-of-an-object.jpg",
        "published": "true"
   }
}

Supporting ALC Documentation

• ALC: Draft API Endpoint To Generate Arc ID
• ALC: Photo Center Distributor Fields
• ALC: Photo Expiration And Restriction On A Date