Difference between revisions of "API Design experience"
(→Output) |
|||
| (2 intermediate revisions by the same user not shown) | |||
| Line 9: | Line 9: | ||
=== API version number === | === API version number === | ||
Add the API version number to each call as a path (Robotoff) | Add the API version number to each call as a path (Robotoff) | ||
| + | === Path parameters vs Queries === | ||
== Output == | == Output == | ||
| − | === Single | + | All API calls should result in a json response. |
| + | |||
| + | === Single json response === | ||
=== Response wrapper === | === Response wrapper === | ||
| − | The wrapper contains the meta data of the response, i.e. whether the request was successful, how many results are available, etc. | + | The wrapper contains the meta data of the response, i.e. whether the request was successful, how many results are available, etc. The usual possible parameters: |
| + | * status (string) - the quality of a successful response: '''found''' or '''not found'''. | ||
| + | * count (uint) - the number of results | ||
| + | Missing from this wrapper are the original query, which would make the json-response independent of the query. It would be nice to have as well: | ||
| + | * number of items in response (uint) - how many items are contained in the response? | ||
| + | * page number (uint) - which page do these items belong to (is page 0 the first 25 items?) | ||
| + | * time stamp (time) - so when we look at the json later we can tell how old the data is. | ||
| + | |||
=== Free dictionaries === | === Free dictionaries === | ||
=== Dependent field names === | === Dependent field names === | ||
[[Category:API]] | [[Category:API]] | ||
Latest revision as of 15:01, 26 November 2022
Introduction
This page reflects my experience in using the various API suites (product, search, image, robotoff, folksonomy) available on OFF. These implementations can sometimes be streamlined and synchronised.
My experience is based on implementing the API's in Swift 4.0 on Xcode. I want to be able to implement the API's only with the Swift libraries and minimal coding. If I need to cater for an exception in the API or the Json -results, then there is something wrong in the API design.
API Call
Is it possible to streamline the various API calls?
API version number
Add the API version number to each call as a path (Robotoff)
Path parameters vs Queries
Output
All API calls should result in a json response.
Single json response
Response wrapper
The wrapper contains the meta data of the response, i.e. whether the request was successful, how many results are available, etc. The usual possible parameters:
- status (string) - the quality of a successful response: found or not found.
- count (uint) - the number of results
Missing from this wrapper are the original query, which would make the json-response independent of the query. It would be nice to have as well:
- number of items in response (uint) - how many items are contained in the response?
- page number (uint) - which page do these items belong to (is page 0 the first 25 items?)
- time stamp (time) - so when we look at the json later we can tell how old the data is.