2020-12-05 Saturday - Variations in API Filter Syntax

Variations in API Filter Syntax

Doing a bit of research today on variations in how different API implementations have chosen to support filter syntax. This blog post is a placeholder for organizing additional examples that I am working collect and organize.

1.0 References

1. https://en.wikipedia.org/wiki/Query_string 
1. " Various ad hoc limitations on request-line length are found in practice."
2. "The common workaround for these problems is to use POST instead of GET and store the parameters in the request body."
2. RFC 3986 - Uniform Resource Identifier (URI): Generic Syntax
3. https://www.programmableweb.com/category/all/apis 
   

2.0 Query Syntax Examples

2.1 Elastic Search Query Syntax:

Elastic Search query syntax:

• https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax

• FDIC: BankFind Suite: API for Data Miners & Developers
• https://banks.data.fdic.gov/docs/

2.2 Github.com 

1. https://docs.github.com/en/free-pro-team@latest/rest/reference/search  
• NOTE: Syntax, request & response examples shows on this page
  
• The Search API does not support queries that:
• "are longer than 256 characters (not including operators or qualifiers)."
• "have more than five AND, OR, or NOT operators."
• "GitHub Search API provides up to 1,000 results for each search."
  
• Note: Uses the page metaphor: "Results per page (max 100)" 
• TO-DO: verify if the API still uses the "per_page" parameter
  
2. https://docs.github.com/en/free-pro-team@latest/github/searching-for-information-on-github/understanding-the-search-syntax
   
3. https://docs.github.com/en/free-pro-team@latest/github/searching-for-information-on-github/searching-on-github
• Finding Files on Github
• https://docs.github.com/en/free-pro-team@latest/github/searching-for-information-on-github/finding-files-on-github
  
• Search code:
  
• https://docs.github.com/en/free-pro-team@latest/github/searching-for-information-on-github/searching-code
  
• "Only files smaller than 384 KB are searchable."
•  
  
• Search commits 
• https://docs.github.com/en/free-pro-team@latest/github/searching-for-information-on-github/searching-commits
  
• Search issues and pull requests
• https://docs.github.com/en/free-pro-team@latest/github/searching-for-information-on-github/searching-issues-and-pull-requests
  
• Search labels
• Search repositories
• https://docs.github.com/en/free-pro-team@latest/github/searching-for-information-on-github/searching-for-repositories 
  
• Search topics
• https://docs.github.com/en/free-pro-team@latest/github/searching-for-information-on-github/searching-topics
  
• Search users
• https://docs.github.com/en/free-pro-team@latest/github/searching-for-information-on-github/searching-users
• Search packages
• https://docs.github.com/en/free-pro-team@latest/github/searching-for-information-on-github/searching-for-packages
• Searching wikis
• https://docs.github.com/en/free-pro-team@latest/github/searching-for-information-on-github/searching-wikis  
• Searching Github Marketplace
• https://docs.github.com/en/free-pro-team@latest/github/searching-for-information-on-github/searching-github-marketplace
  

3.0 Review Backlog: Other API collections to examine:

1. Wikipedia
   
2. Twitter
3. YouTube 
4. Box
5. DropBox
6. LinkedIn
7. Yelp 
8. Indeed
   
9. Fadcebook
   
10. Twilio 
    
11. Etsy
    
12. PayPal
13. Ebay
14. Concur
15. Uber
    
16. SoundCloud
17. Rotten Tomatoes 
18. Reddit
19. Thomson Reuters
20. Basecamp
21. Kiva
    
22. Fitbit
23. Vimeo
    
24. Stripe
25. Salesforce
26. Coupa.com
27. SAP
28. Google
29. AWS
30. Azure

4.0 Additional Suggested Reading

1. https://apievangelist.com/
2. http://apistylebook.com/  
• http://apistylebook.com/design/topics/collection-filtering
  
• http://apistylebook.com/design/topics/resource-retrieve-partial
  
3. https://www.moesif.com/blog/technical/api-design/REST-API-Design-Filtering-Sorting-and-Pagination/ 
4. https://www.progress.com/blogs/rest-api-industry-debate-odata-vs-graphql-vs-ords
   

 

5.0 Suggested Books

1. The Design of Web APIs, 1st Edition, by Arnaud Lauret
• https://www.manning.com/books/the-design-of-web-apis
  
• In particular, see sections 4.3, 4.4, 
• And section 10.3
• https://livebook.manning.com/book/the-design-of-web-apis/chapter-10?origin=product-toc