In my RAML 1.0 spec, I would like to represent a uriParameter whose value is one of a set list of enumerated tokens. For example, _format can only be one of: csv, json or ttl.
As far as I can tell from reading the RAML spec, that's not possible at the moment unless I include JSON schema declarations. Can RAML encode enums without JSON schema, and if so, how?
Yes you can, by using RAML 1 data types:
"Data types can describe a base or resource URI parameter, a query parameter, a request or response header, or a request or response body. Data types are built-in or custom. A built-in type can be used anywhere the API expects data. Custom types can be defined by extending the built-in types as well as named and used like built-in type"
Example:
#%RAML 1.0
title: bla
types:
foo:
type: string
enum: [ json, csv, ttl ]
/bar/{_format}:
uriParameters:
_format:
type: foo
get:
Related
I am trying to set up a service that consumes Kafka topics. I am stuck at current part.
When topic is consumed I get back something like:
�{"id": "df7c4bb5-dc19-40f2-9f0a-77956c15be15", "dob": "1924-12-07", "last_name": "Doe", "first_name": "John",} created
which I think is Avro format I presume
Now, any idea how this can be parsed? I would love to have some type of data class or class in general defined as:
val id: String,
val first_name: String,
val last_name: String,
...
)
And map that value to it. Tried some libs, but couldn't quite make it to work. Thoughts, examples?
Based on the leading character, it looks like Avro, yes, however it might be simply be an Avro string type rather than an object with individual fields...
In any case, if you use the Avro maven plugin (there's a different plugin for Gradle) and define a schema matching the record (seems like you might be using a Schema Registry, so you can get the schema from there), then Maven will build a matching Java class for you (mvn compile) to use from Kotlin.
Upon consuming the data with an appropriate AvroDeserializer class, your record will be deserialized to that type
This question already has an answer here:
Reusing a subset of an enum in OpenAPI (Swagger)
(1 answer)
Closed 2 years ago.
Let's say in my OpenAPI v3 description, I have the following /componenets/schemas entry (using YAML) format:
WidgetTypes:
type: string
enum:
- WIDGET_A
- WIDGET_B
- WIDGET_C
The WidgetTypes schema is thus a named (i.e. value $ref) enum 'class'. In various other places in the API spec, we can now refer to these enum values, e.g. perhaps there's an API path for which one of the path elements must come from the WidgetTypes set.
Now, I have also some additional schemas (i.e. object data models), and there might be a case where a specific WidgetType value is a constant for that object type. An example:
MySpecificWidgetA:
type: object
properties:
someField1:
type: string
someField2:
type: number
widgetType:
type: string
enum:
- WIDGET_A
This feels like the naïve way to accomplish this, since now MySpecificWidgetA's widgetType field is a string that comes from the set of possible WidgetType's, but there's no actual reference to WidgetType enforcing this.
In spirit, what I'd like to assert is that MySpecificWidgetA.widgetType is a specific value from the WidgetType enum schema (in this case WIDGET_A).
Using just $ref: '#/components/schemas/WidgetType' passes validation, but doesn't accomplish what I want: it states widgetType is simply a value coming from that set ... I want it to be a restricted value from that set (i.e. a constant).
I've tried experimenting with $ref a few other ways for the value of widgetType, including (without success):
$ref: '#/components/schemas/WidgetType/WIDGET_A'
$ref: '#/components/schemas/WidgetType/enum/WIDGET_A'
$ref: '#/components/schemas/WidgetType/enum/0'
(the last one being not very useful, but just testing out the exact JSON Pointer format that $ref uses.)
None of these attempts above pass the OpenAPI v3 validation ... does anyone know if it's possible to reference (via $ref or some other mechanism) a specific value from a defined enum schema element?
This is not allowed by JSON Schema. $ref is only allowed to resolved to other schema objects, not to individual data points.
TLDR
I want a kotlin utility to call a 'GET' method on a restful API. Must I-the-programmer define a class that matches exactly the json output? Can I skip fields, so that the 'value/return object' class includes some of the returned fields, but not others?
Background
I'm new to kotlin and switch-hitting between python and kotlin.
I'm writing a utility to get data from a restful api. The vendor provided documentation and examples.
In python, the 'get' method would return a 'Map of maps'. The kotlin way, in contrast, is to return a 'well-defined' object.
I-the-coder can 'poke around' with this 'returned object' for the 'information I need'
Example
For example, let's say I want to 'get customer' from the rest api and my-utility only wants these fields:
'name'
'member since' date.
But let's say the 'get customer' json object includes a whole-bunch-of-info I-the-programmer don't care about:
"order history" (each entry in the 'order history' list is itself a complex object)
"customer preferences"
In kotlin: do i need to define a class that matches each and every field on the returned object? Can I define only the 'fields I care about' and have the 'json parser/object mapper' ignore all other fields?
Vs SOAP
Back in the day (e.g. 2006), applications providing SOAP services would generate java-client classes from the WSDL. Does the kotlin programmmer need to do the equivalent for restful programming?
Json Libraries
I didn't mention any specific parser (jackson, gson, klaxon) because I'm more interested in the general approach and assumed the "kotlin side" would be similar fo reach.
Most JSON parser libraries have an option to ignore unknown attributes in JSON data - for example, here's Jackson's documentation for this. If you set this option, you'll be able to create data classes that only contain fields you're interested in.
Using Microsoft Bond (the C# library in particular), I see that whenever a Bond struct is defined, it looks like this:
struct Name
{
0: type name;
5: type name;
...
}
What do these numbers (0, 5, ...) mean?
Do they require special treatment in inheritance? (Do I need to make sure that I do not override members with the same number defined in my ancestor?)
The field ordinals are the unique identity of each field. When serializing to tagged binary protocols, these numbers are used to indicate which fields are in the payload. The names of the fields are not used. (Renaming a field in the .bond file does not break serialized binary data compatibility [though, see caveat below about text protocols].) Numbers are smaller than strings, which helps reduce the payload size, but also ends up improving serialization/deserialization time.
You cannot re-use the same field ordinal within the same struct.
There's no special treatment needed when you inherit from a struct (or if you have a struct field inside your struct). Bond keeps the ordinals for the structs separate. Concretely, the following is legal and will work:
namespace inherit_use_same_ordinal;
struct Base {
0: string field;
}
struct Derived : Base {
0: bool field;
}
A caveat about text serialization protocols like Simple JSON and Simple XML: these protocols use the field name as the field identifier. So, in these protocols renaming a field breaks serialized data compatibility.
Also, Simple JSON and Simple XML flatten the inheritance hierarchy, so re-using names across Base and Derived will result in clashes. Both have ways to work around this. For Simple XML, the SimpleXml.Settings.UseNamespaces parameter can be set to true to emit fully qualified names.
For Simple JSON, the Bond attribute JsonName can be used to change the name used for Simple JSON serialization, to avoid the conflict:
struct Derived : Base {
[JsonName("derived_field")]
0: bool field;
}
I know returning types in a wcv service is allowed, and it will convert the object to json. But what if I don't want to return a random type, but return a string with formatted json? I can construct json my self but it can a) be messy, and b) not auto encode html values.
How do I do build a custom formatted json string? Off the top of my had, can I return a dictionary with key, value pairs? Will the value be encoded so you can transmitted without running the risk of malformed json?
Have a look at JSON.Net. I've used it in the past for serializing/deserializing to/from Json. It also (according to the web page) has support for converting Json to/from XML, so it seems reasonable that there would be some functions in there to build arbitrary Json strings in a way that is less error-prone than doing it yourself.
You can specify a return type of object and then use an anonymous type to return an arbitrary object. If you want to return an arbitrary collection, you can return IEnumerable, and use that to return a collection of anonymous types.
as far as I can understand, you want a webservice that returns a string that can be parsed using json (like JSON.parse(yourReturnedString)... As ckramer answered, JSON.NET can help to format your whatever dictionary into json but you should know dictionary is "json-serialised" as key:'your key', value:'your value§that can be also an object that will be serialized', so if you are using JSON.NET, you should also once it has been deserialezed, remove all the "key": and ,"value" JSON.NET returned.
so good so far you should definetely declare your webmethod as a method that returns a JSON format.
hope you found a solution before this answer...