When to use which retrival API

image avatar

Ashish Dandgawhale

Posted Jan 06, 2022

Background for the question - I'm one of the software developers from a software-based MNC  and we are working on one of our client's app requirements which is to build a connector kind of app around Zendesk  API. I have thoroughly gone through Zendesk's API documentation and I see there are multiple APIs for retrieving the records of various objects.

Broadly I found there are 4 categories of APIs for records retrieval/fetching

Following is our understanding for each of the retrieval APIs castegory, we just want clarity on which category of API to use over others in which case.

1. Object-specific APIs
Example: /api/v2/tickets or /api/v2/users

  • I don't see many limitations on this category of APIs, we can retrieve all the tickets, we can also retrieve the individual record by using its ID, and we can get all tickets of a specific user or specific organization.
  • The only limitation I see here is that we can not search tickets by different ticket properties like tags or create/update date&time
  • I did not see any documented retrieval limit on this API, even if there are a million records, I believe I can retrieve them all using pagination if I'm not wrong.

2. General Search API
Example: /api/v2/search

  • I can search the object like ticket/user/org with this API
  • Search with many different object-specific properties is possible like with tag, user, data&time
  • Available records to search are not immediately available, it takes some time for records to get indexed
  • I can only retrieve a maximum of 1000 records with this API
  • Probable use case: To search the records when lesser results are expected

3. Export Search API
Example: /api/v2/search/export

  • I can use date&time filters, and also search using different other properties specific to the object.
  • I did not see any documented retrieval limit on this API, even if there are a million records, I believe I can retrieve them all using pagination if I'm not wrong.

4. Incremental Export API
Example: /api/v2/incremental/tickets

  • We can only make 10 requests per minute
  • There is no provision to search the records
  • We don't get the record of the current minute running
  • We can keep exporting the records until the last record is found with either cursor or time pagination
  • Up to 1000 records can be fetched in each page
  • I did not see any documented retrieval limit on this API, even if there are a million records, I believe I can retrieve them all using pagination if I'm not wrong.
  • Probable use case: To export the records quickly to some other env or account

- We have confusion over the following two API categories,  Object-specific API and Export Search API. Why not use Export search API over object-specific-API? Since at least we did not find anything that Object-specific API can do but not Export-search API. Export-search API can do many other things that object-specific API can not do, And also there are no documented limitations on Export-search API? So We think the export-search API is the best API for most of the use cases of retrieval on ticket/user/organization

- Also we were wondering why to use general search API when export search API can do pretty much the same things without any limits on the number of output records?

Please correct us if we are mistaken

1

3

3 comments

Date
    Newest
      image avatar

      Todd McDermid

      I would also like to let Ashish know that one of his assumptions is incorrect, and would appreciate some guidance (as I'm sure he will when he finds this out) from Sabra or any other community member.

      Ashish, when you "did not see any documented retrieval limit on this API, even if there are a million records, I believe I can retrieve them all using pagination if I'm not wrong." you are correct - there is no documented limit. However, there is an actual undocumented limit. The pagination "session" you start with the first call of any of the APIs starts a clock. That "session" will timeout and be disconnected after one hour.

      I have started another post here (Best pattern for periodic bulk export of ZenDesk objects – Zendesk help) hoping to understand ways to circumvent that issue. Perhaps it will be of interest.

      0

      image avatar

      Ashish Dandgawhale

      Thank you @Sabra for clarification. I just wanted one more clarity about Search Export API. When you said it's rate-limited to 100 requests per minute per account, does that mean per OAUTH2 account or per user account on whose behalf we are making the requests?

       

      Like if we have one Global AUTH2 app let's say XYZ.

      Using this XYZ app, I authentication two different user accounts ABC and user MNO. Here both the user ABC and MNO are from two different subdomains.

      So now my question is whether the limit of 100 req/minute applies to the XYZ app itself or this limit is for every account separately, account ABC can make 100 req/minute, and also simultaneously MNO can make 100 req/minute.

       

      0

      image avatar

      Sabra

      Hey, Ashish! At the end of the day, the way you decide to retrieve information is going to depend on your use case and what makes the most sense for what you are trying to accomplish. That being said, there is a lot of overlap in terms of what the APIs do. For example, if I was designing an app where I wanted to present recent tickets associated with an organization, I could use the List Tickets API and simply display results:

      GET /api/v2/organizations/{organization_id}/tickets

      I could also use the General Search API to get the same information, plus a little more. One of the nice things about the General Search API is that it will include archived tickets, unlike the List Tickets API. 

      GET /api/v2/search.json?query=organization:{organization_id} type:ticket

      Now, since my goal is to present recent tickets associated with an organization, I need to decide what I want to consider "recent tickets". Does recent ticket to me mean all non-archived or does it mean something else (i.e. everything in the past 2 years)? Depending on the answer to that question, one of these would be more appropriate than the other. 

       

      As for the Search Export API, the same concept applies -- it's just going to depend on your use case. As mentioned in the documentation, this endpoint is for search queries that will return more than 1000 results. The result set is ordered only by the created_at attribute, unlike other endpoints, where you can specify the sort order (i.e. General Search API).

      Additionally, as mentioned in our documentation, the Search Export API endpoint is rate-limited to 100 requests per minute per account. The limit also counts towards the global API rate limit.

      0

      Sign in to leave a comment.

      Didn't find what you're looking for?

      New post