I'm currently working on implementing a Pub/Sub pattern for a project I'm working on and I was wondering why the content was JSON encoded string when the rest of the message was in plain JSON.
I couldn't find any documentation on this topic, generic documentation on the Pub/Sub pattern is not really abundant, or I didn't use the good search terms.
If content was not encoded separately like that, then the server would need to be aware of the contents of the message in order to deserialize. With this approach, it can simply treat the content as a string and forward that encoded string along to subscribers.
Related
I'm using protobuf to serialize json from api for flutter app.
however I'm having an issue where I need to serialize this list for example:
"value_array": [ "",
"",
null
]
If I use the usual:
repeated string value_array = 6;
I get an exception during parsing the json.
and sadly I can't have the json changed from api. even worse I can't just manually remove the null from json before parsing it as this element in json is repeated in many different api calls.
PS. I don't need to differentiate the empty string from null, just want to avoid the exception.
thanks in advance for any help.
protobuf has a very opinionated view on JSON, and not all JSON concepts map cleanly to protobuf concepts; for example, protobuf has no notion of null
It might be fine and reasonable to use the protobuf JSON variant if you're always talking protobuf-to-protobuf and want readability (hence text over binary), but if you're working with an external (non-protobuf) JSON tool, honestly: don't use protobuf. Use any relevant JSON-specific tool for your platform - it will do a better job of handling the JSON and supporting your needs. You can always re-map that data to your protobuf model after you have deserialized it, if you need.
I'm trying to learn how to create an API (I use Laravel in the backend and Postman to send requests), but I have a basic doubt when sending data to be processed in the backend.
I see that there are several ways to send data to the backend, but I'm not sure which is the right way to do it.
For example, with Postman I have seen that the sending can be done as parameters through the URI:
www.example.com/api/v1/orders?limit=10&offset=20
I can also do it in the body of the request through the tags
form data
x-www-form-urlencoded
raw
other ...
I understand that I can make the request along with sending data in several ways. I would like to know what should be the correct, standard or optimal way to do it for usual requests such as getting a series of records with a filtering, an order or a pagination.
I would also like to know if the way of sending data should depend on the verb to be used in the request.
My main question/problem is that I would like the way users use the API to be as simple or suitable as possible for them. I'm clear that I want to always return the data (when necessary) in JSON format but I'm not clear on how it should be sent.
Please, could someone clarify these doubts (maybe a link to a page where this kind of doubts are dealt with).
Thank you very much in advance.
It depends:
GET, HEAD and DELETE don't have a request body so all parameters have to be send via URL
POST can be easily sent via form data in Laravel
For PUT/PATCH I prefer application/json because PHP sends it via php://input stream which can have some problems in Laravel sometimes
You can also combine URL parameters and the request body. Compound types (for example models) can only be send as one via request body while it might suffice to send an id via URL parameter.
I guess, nearly more important is the overall format and documentation. The format should be consistent, easy to understand and maybe standardized (for example: https://jsonapi.org/format/#crud).
Keep in mind that forms do two things by default:
Only having methods GET and POST
Only having ectypes application/x-www-form-urlencoded, multipart/form-data and text/plain
If you want to enforce something else, you have to use scripts/libraries to do this.
Nowadays, it appears that JSON content (for POST, PUT, and PATCH) is the most popular and readable. It is well recognizable and clean. Examples in the documentation are easy to read.
I would go for JSON for both, incoming parameters and the outgoing response. This regards parameters related to the business logic of your application.
At the same time, for GET, HEAD, and DELETE methods, you don't have a payload at all. For parameters related to controlling the API (i.e. not strictly related to the business logic of the application, but to the API itself) I'd go for query parameters. This applies to parameters like limit, offset, order_by, etc.
P.S. There is only one caveat related to the JSON format. If your API happens to have file parameters you may face the problem. You can still use JSON format, but in such a case, you should encode your files (e.g. using base64) and put it as string parameters of your JSON. This may be demanding for the consumers of your API ;) This will also enlarge your files and will probably force you to process these files in memory. The alternative is to use multipart/form-data as a request Content-Type - this way you can have both, the form and separate "space" for files. It's worth keeping this case in mind when you decide.
We are exposing swagger-ui from our webserver using the Swashbuckle package working on top of Asp.Net Core. We are hitting an input validation issue for our Guid input fields.
The GUIDs we are pasting in, which are read from other parts of the system, are formatted as deb83f8a3edc4b78a2ece3321f81b58b, note the missing dashes. The input validation rejects this as it expects dashes in the format (so it accepts deb83f8a-3edc-4b78-a2ec-e3321f81b58b).
The swagger document that we serve has the parameter as type: string and format: uuid. It calls to some internal validationGuid call that have a reg-ex that forces the dashes. From the browser Console it seems like it is looking for a component called JsonSchema_string_uuid but is not finding it.
So my question is how can I extend swagger-ui to override the validation of specific parameter type/formats?
UPDATE:
I was made aware of the RFC that specifies a UUID as containing dashes and a workaround. However, I'm still interested in learning about ways to customize the validation of both custom formats and specifically uuid?
While the OpenAPI Specification and JSON Schema do not currently define format: uuid, RFC 4122 defines UUID as containing dashes, and some comments in the OpenAPI repository suggest that format: uuid is supposed to follow RFC 4122. This means your example without dashes is most likely not format: uuid.
Consider replacing format: uuid with pattern: '^[A-Fa-f0-9]{32}$'.
I'd like to be able to document the parameters as if they were URL parameters, since I like how that bit of documentation renders a handy table. However, in my API, I would like those paremeters to plug into the JSON body rather than the URL. Is there a way to achieve this?
The dedicated syntax for describing, discussing (and thus also validating) message-body is in the making.
It will be based on the Markdown Syntax for Object Notation, similar to the actual URI Parameters description syntax (eventually these two should converge).
Also see related How to specify an optional element for a json request object and Is it possible to document what JSON response fields are? questions.
Working in front-end we never know the back-end language so how can I know whether the
data coming from back-end is in json or in text or in html or in xml. We don't have an authority or access to back-end language.
Some languages declare this in the first line or 2... Why don't you just read the first few lines or the code?
Many languages will allow you to parse XML, not ideal to wrap it in a catch but it would work. However, you neglected to state what language you are using.
However, it may be worth while agreeing on a format, something like XML which you can then de-serialize ?
You can check Content-Type in Response Headers to know the response data type.