NameĪ 2-character country code of the country where the results come from. You must URL encode the query parameter values. The Required column indicates whether you must specify the parameter.
Solve for the problem you have, not a problem that you may have some day.The following are the query parameters that the request may include. This is why it really matters what your product actually is. If you have a few inputs on a web page and they map directly to known SQL predicates, you may be going overkill with the JSON pattern. Elasticsearch supports any sort of user-defined schema, so they expose a general query language as JSON. need to be dynamic because the JSON structure is actually meant to be a search query. The set of filters being passed in, operators, etc. For example, if the frontend always performs a wildcard search, then testing the = case for name is a waste because it's never really used, but your API supports it, so it better work.ĭespite all my concerns with this approach, Elasticsearch does the JSON pattern and it works quite well for them.
If your clients only use the API a single way, then you have a bunch of unused use cases you are stuck supporting. If your API allows for any operator across any field, you need to test each one of these cases.
Testing overhead - following from the complexity point above, every combination of criteria needs to be tested. If there are only 4 things to filter on and they always work the same way, hard coding will save you a ton of time. Complexity - Do you really need to support infinite filters or even a dynamic list of filters? Do the operators need to be configurable like that? This JSON object design is highly extensible. Moving your inputs to a JSON object may create a black box, forcing you to validate inputs yourself (and we all know that inadequate input validation is one of the leading causes of security vulnerabilities) Validation - There are modules which can automatically validate a request based on a schema you supply. You'd have to do your own parsing if you go the JSON route, but that's not hard. 
For example, in a node.js express app, I can check to get the filters.
Tooling - Most HTTP routing frameworks have middleware to automatically parse query string parameters and expose them as a map. Documentability, if this is important to your organization and/or product. There is a misconception that GET means query string and POST means body. GET requests can accept a body, just like POST requests and POST requests can accept a query string. GET is the semantically correct HTTP verb because you are getting data. I don't totally agree with the pushback against GET that you have received in other answers. Your use case might be a good candidate for this. In certain cases, like building up a dynamic set of search filters, it might make sense. That said, I don't think this pattern is necessarily bad. Adhering to common conventions and expectations simplifies things and helps avoid mistakes. Inconsistent with the rest of the world. API documentation, accessibility, and discoverability were important to us. Swagger (our API documentation tool) would have no intuitive way to document the structure of this API. Pro: Saved half a line of code in the API implementation In our case, I found the tradeoffs were simply: He was adding a new API endpoint and wanted to pass in a complex JSON object into the query string instead of separate parameters.Įxactly what the pros and cons are will depend on your specific product needs, architecture, team structure, and other factors. I went through almost the same analysis with a former coworker. Is this a bad/good idea? I see advantages and disadvantages, but I'm trying to look past my personal bias. Disregarding that, the basic question is: And I realize that the structure of the JSON object for querying would have to be altered, as it does not account for some things. We are in JavaScript on both client and server, so parsing the JSON object is not a difficult task. Which, after encoding, looks something like this as a URL (sorry if I messed up the encoding, I made this up as an example): GET /api/v1/widgets?filters=&pagination=%7B%22page%22:%222%22,%22pagesize%22:%2225%22,%22sort%22:,%22sortdirection%22:%7D This would result in SQL something like SELECT I'm building an API endpoint for a UI grid to search, filter, and display a list of domain objects, let's call them "widgets." In the past, I would have built this with a list of named query string parameters, like this: GET /api/v1/widgets?type=2&name=what&from=&to=&pagesize=25&page=2&sort=name,-createdate
0 kommentar(er)
