API FAQs

Here are some important points that you need to consider:

• Limit Response Payload: GET calls usually return a lot of unwanted parameters. If the APIs are used excessively, the default API response not only increases infrastructure load but also starts impacting the performance of your app. It's important to validate data and filter out anything that shouldn't be there.
  
  Ideally, the best practice is to limit your response payload to 5 MB.
• Keep the total number of “includes” and “level depth” to the minimum: When retrieving data, always make sure you decide logically what you need to extract and avoid retrieving unnecessarily large data.
  
  It is recommended to keep the number of includes (when referencing other entries) and the depth levels as low as possible. The best practice is to restrict your total include to not exceed 10. However it depends on the user’s requirement (and their final response payload size, which should be restricted to the ideal response size mentioned above).
  
  
• Make use of projection queries: To restrict the size returned in your response payload, make sure to use projection queries such as only, except, etc. These projection queries allow you to retrieve/exclude specific field data for each entry.
• Make use of pagination: If you think that your response payload can be overwhelming, you can use skip and limit parameters to paginate your response.
• Use “Lazy loading”: This factor totally depends on the user and also on the framework that they use. If the website data is pulled in from multiple content types, lazy loading is a good approach that will let them load the important sections of their website first before loading the others.

Exceptional Use Case

So what do you do if you might hit the limits even after following the above precautionary measures?

In this scenario, you can make use of filtering or pagination. What does this mean? Let’s look at the steps involved:

1. First, you can divide your includes into multiple calls, say you need to add 10 includes. You can split them into groups of, maybe, two.
2. You can append projection queries such as only, except, etc. to these batches to retrieve restricted response.
3. [Optional, but recommended] Now, if you feel your response can be overwhelming, you can use skip and limit parameters to paginate your response.
4. Finally, you can merge the results of all the batches together to get your final response.

Yes, the “Publish Later” option is supported in REST API calls as well. When passing the publish entry details in the body parameter of the Publish an Entry POST call, you need to provide the “scheduled_at” key with the publishing date/time in the ISO format as its value. 

The body parameter should look like this:

{
    "entry": {
        "locales": [
           ...
        ],
        "environments": [
            ...
        ]
    },
    "locale": "en-us",
    "version": 1,
    "scheduled_at": "2016-10-07T12:34:36.000Z"
}

By default, Contentstack's Image Delivery API optimizes the JPEG or WebP images by 85%. When you use optimization on images, it tends to increase the size of the original image. However, it reduces overall bandwidth over multiple images delivered from the API. So, a few images that were available in lower sizes are delivered in larger sizes when retrieved through the API.

Yes, Contentstack gives you the provision to automate release postings via “POST” calls. You can schedule the entry to be published at a later date/time by adding the “scheduled_at” key in the Body parameter. When passing the publish entry details in the Body parameter of the POST call, you need to provide the publishing date/time in the ISO format as the value of the “scheduled_at” key. The Body parameter should look like this:

{
    "entry": {
        "locales": [
           ...
        ],
        "environments": [
            ...
        ]
    },
    "locale": "en-us",
    "version": 1,
    "scheduled_at": "2016-10-07T12:34:36.000Z"
}

Yes, we have open APIs for Content Delivery and Content Management.

Content Delivery API helps you to retrieve data and Content Management API allows you to create, access, and manage data.

Yes, Contentstack uses Fastly—a leading content delivery network (CDN) provider—to provide lightning-fast content delivery to users anywhere in the world.

Yes, this is possible. You need to execute the “only[BASE][]” query and provide the unique IDs of only those fields that you wish to retrieve, as its parameters. For more details, refer to the Only Operator section in our Content Delivery API.

Image Delivery APIs are image manipulation and optimization API calls. The API calls will help you to retrieve, manipulate, and/or convert image files of your Contentstack account and deliver it to your web or mobile applications.

You can resize an image by specifying the “width” and “height” of the image.

• width: The “width” parameter lets you dynamically resize the width of the output image by specifying pixels (as any positive integer between 1 and 8192) or percentage values (as a percentage value between 0.0 and 0.99). In case of percentages values above 99, append a ‘p’ parameter to the value).
• height: The “height” parameter lets you dynamically resize the height of the output image by specifying pixels (as any positive integer between 1 and 8192) or percentage values (as a percentage value between 0.0 and 0.99). In case of percentages values above 99, append a ‘p’ parameter to the value).

To see these parameters in action, refer to our documentation.

You can use a combination of the “crop” and “overlay” parameters to achieve this activity. First, crop the desired section from the source image and then attach it to the final image.

To crop a specific section of an image, you can use the “crop” parameter and pass the desired width and height of the section that you want to remove. The query to be used is ?crop={width_value},{height_value}. For e.g., if you wish to crop an image where you want a width of 300px and a height of 400px from the center, you can specify the values in the above query as ‘?crop=300,400’. To trim only a particular side of an image, use the “trim” parameter.

Later, use the “overlay” parameter to attach the cropped image on top of another. 

You can use the “format” parameter to convert a given image from one format to another.

This can be achieved using the “overlay” parameter. 

The supported formats to which you can convert your source image are .gif, .png, .jpg (for JPEG), .pjpg (for Progressive JPEG), .webp, .webpll (Lossless), and .webply (Lossy).

Image optimization improves the loading speed of a website by reducing the size of uploaded images without compromising on the quality aspect. Optimization ensures a better user experience and swiftly delivers elements of a website to the browser . The reason for faster load speed is essential for a website because it factors into the SEO ranking. Also, the traffic is highly improved when the file sizes are reduced. You can optimize an image by using the “auto” parameter or reducing the quality of an image.

This can be partially achieved by using an overlay image. 

To compress the size of an image you can use the “quality” parameter. This parameter lets you control the level of compression to an image. You can specify the value for this parameter in whole numbers, i.e., between 1 and 100. To add a quality parameter for an image you will need to specify '?quality={quality_value}' after the URL of an image.

You can use the “trim” parameter to trim an image from the sides/edges. This parameter comes in handy especially when you need to remove borders or white spaces around images. The value for this parameter can be given in pixels or percentage.

To trim an image using the “trim” parameter, you need to specify the value for right and left in pixels or percentage “?trim={right_value},{left_value}”

To control the image after using the width parameter, you can disable the upscale of the image by specifying the disable parameter: width={value}&disable=upscale

Yes, you can crop an image using the “crop” parameter to a specific pixel or percentage. Using this parameter, you can remove pixels from an image by specifying the height and width in pixels or percentage value, or defining height and width in aspect ratio.

Yes, the “orient” parameter gives you the ability to orient the image. By using this parameter, you will be able to move an image right, left, horizontally, vertically, or flip. 

The “quality” parameter supports only the lossy file format and thus is not applicable for image formats such as PNG and GIF because they are lossless file formats. Refer to our documentation for more details.

If the border is added as the background of the image, you can change the color using the “bg-color” parameter.

There is no specific format for uploading images. For performing image transformation activities, you can upload images in any convenient format or resolution. If you wish to convert the format of any image, you can use the “format” parameter.

Image Delivery API calls can transform your images on demand. It can dynamically resize, convert, adjust quality, crop/trim, change orientations, and image background colors.

They operate via a query string URL of the API call. When a user makes a request for an image, the Image Delivery API does two things:

1. Serves the desired image request from cache (cache hit).
2. Transforms the source image based on the parameters in the URL of the API call.

Yes. Images can be presented in ultra high definition formats allowing you to serve pixel perfect images on everything from mobile devices to 4K monitor displays.

The browsers supporting WebP image format are Google Chrome, Opera, and Android browsers.

In such cases, you can use the progressive JPEG format which is supported by most of the modern browsers.

The “quality” parameter supports all images of the Lossy file type. The formats included in the Lossy file type are JPEG, Progressive JPEG, and WEBP(Lossy).

To display an image within a circle, use the “overlay” parameter. The overlay image should have a circle of transparent pixels within it. When you place this image over the actual image, the actual image will be displayed within a circle. Now, if the color of the solid background of this overlay is the same as the color of the background where the image will be placed in your app, it will give a circular cropped image effect.