i've tried to find a similar answer but couldn't, so here it goes:
When defining the schema for a json document, if we define an attribute as required, is this requirement for input data, or is it for input and output?
Example:
let's say we have a property called Id. This Id always exists for the resource, but this Id is generated by the server. If i want to publish my schema for public consumption, and i allow someone to create instances of this resource, should the Id be defined as required or not? Are the required properties only those that the consumers of the API MUST send to create the resource, or are all the properties that the resource always have, including server generated properties?
If you need to validate that the "id" key is there then you should make it required. What you could do is have two different schemas: one to validate the schema from the user (sans "id") and one to validate the api call one which would include the "id" key
Related
I'm running a local server playing around with an API using Django. I have a model called 'Users' populated with a few objects, and am using DefaultRouter.
I want to know what the URL would be if I were to DELETE a specific object from this model. For example, if I wanted to GET a user with an ID of 1 in this model, the URL would be: "localhost:8000/Users/1/". What would the equivalent be to DELETE this user?
I found an explanation of this on the REST API website (below), however, I don't understand what any of the syntaxes means.
What is {prefix}, {url_path}, {lookup} and [.format]? If anyone could provide an example of what this might be using a localhost that would be really helpful.
Thanks
Let us take an example of an API (URL) to update book data with id (pk) being 10. It would look something like this:
URL: http://www.example.com/api/v1/book/10/
Method: PUT/PATCH
With some data associated.
If you want to delete you just need to change method to DELETE instead of put or patch.
Regarding your second question lets compare the url with the parameters.
prefix: http://www.example.com/api/v1/book
lookup: 10
format: It specifies what type of data do you expect when you hit the API. Generally it is considered to be json.
url_path: In general, every thing after look up except query string is considered to be url_path.
I am doing an HTTP GET request to /maximo/oslc/os/mxsr and using the oslc.select query string parameter to choose:
*,doclinks{*},worklog{*},rel.commlog{*},rel.woactivity{*,rel.woactivity{*}}
This lets me get related data, including related worklogs, but the worklog does not include the 'description_longdescription' field.
The only way I seem to be able to get that field is if I do a separate HTTP GET to query a worklog id directly through /maxrest/rest/mbo/worklog . Then it provides the description_longdescription field.
I understand this field is stored separately through the linked longdescription table, but I was hoping to get the data through the "next gen" oslc api with one http get request.
I've tried putting in 'worklog{*,description_longdescription}', as I read somewhere that longdescription is a "non-persistent" field and must be explicitly named for inclusion, but it had no effect.
I figured out that for the /maximo/oslc/os/mxsr object in the API, I needed to reference the related MODIFYWORKLOG object through the rel.modifyworklog syntax in the oslc.select query string:
oslc.select=*,doclinks{*},rel.modifyworklog{*,description_longdescription},rel.commlog{*},rel.woactivity{*,rel.woactivity{*}}
I also had to explicitly name the non-persistent field description_longdescription for it to be included.
Ref. for the "rel." syntax: https://developer.ibm.com/static/site-id/155/maximodev/restguide/Maximo_Nextgen_REST_API.html#_querying_maximo_asset_management_by_using_the_rest_api
So I have done some hunting around online, and have been able to figure out how to use the enum tag in a swagger doc to specify a list of possible values for a field. However, in my current API what I need instead is to have a list of potential fields, each of which has a string value.
To be more precise, I have a POST request that sends JSON in the request body. As part of this request users need to send a single ID field. However, we accept multiple types of ID fields. So the request would look something like this:
{name:"name", product:"product", [FirstIdType, SecondIdType, ThirdIdType]:"ID Value"}
So I need to have the user submit a JSON that has a name, product, and one of FirstIdType, SecondIdType, or ThirdIdType. Technically it is required to have exactly one of those three ID types in the request, but I don't really mind if that isn't possible in the swagger doc. Noting it in the description for the field is fine.
The other constraint is that I can't really change the design at this point. The app has already been built using this design and changing it is out of my hands. Which means that I can't just make an array of ID Types and then choose one of them.
Here is the relevant bit from my swagger doc. The area that needs changed is the ID field. Any thoughts or directions on how to get that to go forward would be really appreciated.
definitions:
request_post:
description: (post) request schema
properties:
name:
type: string
product:
type: string
Id:
type: string
Instead of defining what optional fields can come on the path, you can label the fields that are required and make the rest variable by default.
http://swagger.io/specification/#parameterObject
required boolean Determines whether this parameter is mandatory. If
the parameter is in "path", this property is required and its value
MUST be true. Otherwise, the property MAY be included and its default
value is false.
I am making a simple REST API in front of a NoSQL database that stores records as documents similar to JSON (but not exactly the same). Each record has some fields, including id for the database, and also including some derived fields, like dateCreated.
Any time I GET anything, I want to return the objects with all the fields.
// GET /users returns an array of these in JSON
// [{id:"xxx", name:"Bobby", dateCreated:"YYYY-MM-DD"]
data User = User { id :: String, name :: String, dateCreated :: XXX }
But any time I POST or PUT anything, they client should send an object with the id field and any derived fields missing. The database is responsible to create the id when I save it, and I would create some derived fields
// POST /users would need you to post only the name.
// {name:"Henry"}
data PartialUser = PartialUser { name :: String }
If resource represents objects of type User, what should I call the thing client is sending to me? Would you make all the derived fields Maybe values? Or would you create a second object called PostedUser or something?
It can be many things:
a request body
the representation of the intended resource state of the client
a command DTO which you can send to the domain logic in order to process it by CQRS
I would make it CreateUser command, but if you don't want to use CQRS and DDD, then you would probably call it as PartialUserRepresentation, or you don't create a data structure, just use the properties to create a new User entity. Ofc. if you use entities.
So I would say it depends on the architecture of your system.
I'm working on a C# program that retrieves data from a ServiceNow database and converts that data into C# .NET objects. I'm using the JSON Web Service to return my data in JSON format.
What I want to achieve is as follows: If there is a relational mapping between a value (for
example: I have a table called Company, where CEO is not a TEXT field but an sys_id to a Employee Table) I want to be able to output that data not with an sys_id (or just displaying the name property by using the 'displayvariable' parameter) but by an object displayed in JSON.
This means that the value of a property should be an object in JSON instead of just a single value.
A few examples:
// I don't want the JSON like this
{"Company":{"CEO":"b181e841c9212c008aeb36850331fab2"}}
// Or by displaying the name of the sys_id table
{"Company":{"CEO":"James Henderson" }}
// I want the data as follows, so I can have all the data I need inside a single JSON record.
{"Company":{"CEO":{"name":"James Henderson", "age":34, "sex":"male", "office":"SBN Left Floor 23"}}}
From reading the documentation I couldn't find anything in the JSON Web Service that allowed me to display the information like this nor
find any other alternative. It should have something to do with joining the tables and displaying it all in the right format.
I have been using SNC for almost three years and have not found you can automatically join tables in a web service. Your best option would be to use a scripted web service which possibly takes a query parameter and table parameter. Then you can json serialized your result as you see fit.
Or, another option would be to generate a new processor that will traverse the GlideRecord object. The ?JSON parameter you pass in to the URL is merely a flag to pass your request to a particular processor. Unfortunately the OOB one I believe is a Java class not a JS script, so you would need to write a script much like I mentioned earlier to traverse the object path serializing the object graph as far down as your want to go.