Skip navigation

Best practices for getting content in your app

9 min read
Download PDF

Whether you're building your first app or already have one up and running, these best practices will help you keep your users happy.

If you follow the guidelines, your app will become more robust and responsive, always providing the expected results quickly. No matter if there are sudden connection issues, a large burst of requests, or increase in the amount of content, your app will keep working.

Table of contents

    Befriend an SDK

    Instead of directly creating requests and queries to APIs, we recommend using an SDK. SDKs are tools that help you easily communicate with a service, in this case, Delivery REST API. SDKs also help you develop faster.

    There are several advantages to using an SDK in your apps.

    • Resolve hypertext links and render components within your content items.
    • Use strongly typed models so that you easily work with typed content.
    • Rely on the built-in retry policy to handle common connection issues and rate limitation.
    • Easily discover more API features.

    Additions or changes to the Delivery API are often quickly reflected in our official SDKs. Just make sure you're using the latest SDK version available for your technology. All SDKs are open source on GitHub, which means you can submit issues with ideas for improvements.

    Be explicit in what you request

    If all you need is URL slugs of your articles (for example, to build a navigation hierarchy), it's good practice to filter out anything you don't need. In this case, that means requesting only a specific element from a specific type of items in your API requests. Creating more specific requests like this leads to faster responses from the Delivery REST API and smaller response sizes.

    Consider GraphQL

    With's native Delivery GraphQL API, you can query for any number of items with just one request. GraphQL doesn’t require you to make requests to several endpoints. Instead, you create an explicit request for the exact data you need using the GraphQL API, and it fetches the resources for you.

    For best performance when fetching data from via the Delivery REST API, we recommend you follow these guidelines:

    • If you need a single content item, use the retrieve a content item endpoint.
    • If you need a specific subset of elements instead of the whole content item, specify the elements using the elements filter. This applies to linked items as well.
    • If you need to get items based on certain criteria (such as an element's value), use filtering.
    • If you need to get a hierarchy of items (in other words, linked items up to a certain depth), set the depth parameter to a value you require. Try to keep it low. The higher the depth, the higher the response times.
    • If you're building a static site, warming up your app's cache, or exporting your project, use the enumerate content items endpoint. This endpoint is useful when you require most of your project's content (for example, to create a mapping between the items) and don't need linked items.
    • If you're displaying assets from your project, transform the assets to save bandwidth.
    • Use pagination (that is the skip and limit parameters) to decrease the size of a single request and increase speed.

    By using pagination from the beginning, you'll have an easy time even when your project gets bigger and you move from hundreds to thousands of items. API responses may contain up to 2000 content items (including linked content). To check how many items you've got, see the X-Request-Charge header in the API response.

    Need paged navigation in your app?

    If you want to create a paged navigation that displays the total number of items, use the includeTotalCount query parameter in your request. With this parameter, you'll get the total number of content items matching your query. The items omitted by parameters like limit are included in the count.

    Keep in mind that using this parameter may result in slower responses because the API counts the items per request.

    Retry what fails

    Due to the nature of the Internet, any request can fail to some underlying connection issues. It may also happen that the Delivery API denies your request because of rate limitation. If that happens, check the Retry-After header's value, wait the specified number of seconds, and try the request again. Your app should respond to any connection issues by simply retrying the requests after a short while.

    Cache what you get

    Caching helps eliminate the wait time that the users of your app might experience when your app gets content from an API or suffers temporary connection issues. Almost every app that retrieves content (or data in general) from external resources benefits from caching.

    Depending on how quickly you want to display published changes in your app (because not all changes are time-critical), you need to choose a caching approach: either use webhooks and respond to them or go for a time-based cache.

    Leverage stale content if possible

    Most applications don't need updated content right after it's published. Our CDN provides stale content until it is replaced with the updated content in the background. You can recognize stale content by checking if the X-Stale-Content response header is set to 1.

    Save bandwidth on assets

    Instead of downloading all your images in original resolution and full quality, you can dynamically limit the width and height of your images based on device size and other criteria. The image optimization is enabled by default for common image files. You only need to provide a few parameters to make it work. Check out how you can optimize images for the web and use the same approach for other channels like mobile or social.

    Store video with 3rd party

    The Delivery API can download video files from your project but it currently cannot stream them. If you need to store video files and let your users stream them in your app, we recommend using specialized third party services, such as YouTube, Vimeo, and similar.

    Further considerations

    Secure your project

    New projects are publicly available by default. Your project's published content can be accessed by anyone (if they know your project's ID) and they can peek inside. This is usually not a problem for smaller or personal projects. If you need your content to stay private (for example, when internal documents or customer data are part of your content), we recommend enabling secure access in your project.

    Keep in mind that your assets are always public. This includes files such as images, pdfs, office documents.

    Use a static site generator

    If you're building a web app without any dynamic elements like paged navigation or filtered search, consider using a static site generator. Static site generators are tools that take your source code, assets, and content from APIs, and generate your website as a collection of static files. Static sites come with several benefits.

    • Security – Minimal attack vector thanks to not connecting to a database or using CMS plugins.
    • Reliability and speed – Your app becomes a collection of static files and loads swiftly.
    • Scalability and cost – Static sites are usually cheaper to host and they can handle almost any load when paired with a CDN.

    Check out how you can use GatsbyJs, Next.js, or Nuxt.js module with

    What's next?