I'm using Swagger as documentation of my API so that others can use this to build other services reliant on this. I would like to still show the endpoints that are not implemented yet on the UI so that the others can see the expected format of in and outputs, however I would also like to indicate that they are not available yet. Is there some way to disable the try it out feature for example?
Related
I’m trying to integrate a third-party tool with Jira server via REST API.
Currently we have a customized Jira used by our client with a business specific issue types.
Basically all I need is to be able to create an issue of a given type, get response (success/error) and get metadata (list of required and optional fields) for that tool via REST API.
We have a create issue page on WebUI, where user can submit his request.
But the problem is all validation logic is “smashed” between some Javascript code, Behaviours and SIL Programs Manager add-ons, AJS scripts, Jira native fields configuration etc.
So I can’t use “plain” Jira REST API directly because it creates issues without taking in account business rules of a given issue type - e.g. requires fields, one fields can have values depending on another field’s value, an attachment is a required as part of an issue etc.
My question is what is the best way to make an integration with Jira.
I want to be sure if someone will try to create an issue via REST API, the data is consistent according to the issue business rules.
I was thinking to write some "proxy" REST API, which will do the all validation needed and create (or edit) / reject the request.
We've developed a separate Jira plugin which serves some scenarios. So, I can add those API to the plugin.
Or, use Jira REST API endpoints like POST /issue (and PUT /issue/), and I have to define a new screen for it, set all required fields via standard Jira settings, set Cascading fields rules and the standard validator will check if everything is ok out-of-the box?
Sorry, I’m new to Jira and not sure if my current understanding is correct now.
Thanks
Tricky. Best to validate the data in a single place (with one set of code) before calling the create REST API. That way you can also modify the validation logic more easily over time. I think I would probably define a new REST endpoint. ScriptRunner lets you script that nowadays
This is my understanding:
Swagger is a notation/rules to write documentation. But why is it called a framework (like Angular/MVC)?
Swashbuckle is a program (JavaScript?) that generates the documentation (based on Swagger rules).
Swagger UI displays the documentation. It uses Swashbuckle to do this.
Is this information correct? If not can someone explain in simple terms what Swagger, Swashbuckle, and Swashbuckle UI mean?
Also, what do I lose as an API developer if I do not use this?
Swagger is a notation/rules to write documentation. But why is it called a framework(Like angular/MVC)?
It is probably called a "framework" because its' purpose is to offer a systematic way of notating the interface of any RESTful service under the OpenAPI Specification. This is a big deal to developers because the spec is overseen by the Open API Initiative under the reputable Linux Foundation.
Swashbuckle is a program(javascript ?) that generates the documentation(based on Swagger rules)
Swashbuckle is more of a package (or a library) that you can make use of in your .NET Web API projects. It's purpose, as you have correctly indicated, is to generate the Swagger spec for your project. Additionally, the Swagger UI is contained within Swashbuckle so if you are developing an API in .NET it's really a nice one-stop shop of a package. It is almost entirely written in C#, not JavaScript.
Swagger UI displays the documentation. It uses Swashbuckle to do this.
Yes, it does display the Swagger spec in a nice, human-friendly manner. However, Swashbuckle is not a necessary component for this. They are, aside from what I just said previously, completely mutually-exclusive.
Also what do I lose as an API developer, if I do not use this.
This is now entering into the realm of opinion but I'll try to be objective about it. I use Swashbuckle to assist in the creation of clients for my application APIs. After getting past the implementation learning curve (which wasn't much), this package has saved me quite a bit of time of writing the clients myself. Writing a web client is a trivial thing for small applications but enterprise-level applications have a tendency to keep growing and/or changing in complexity so it is nice to have the creation/updating of these clients completely automated.
In short, if you decide not to use it you must either resort on an alternative method of API client generation or write/update the clients yourself. If you are only developing the back end this may be completely pointless to you but it would certainly help whoever is responsible for creating the client apps that will consume your API services.
I hope these answers have been helpful. Cheers!
I've included swagger bundle in each of my dropwizard service. I was wondering if we can run swagger independently and connect to each service so that user can have a centralised view of all services through one UI.
I'm not aware of something that lets you do that at the moment with Swagger UI specifically, but you might check out DynamicApis.com. They let you host multiple swagger documents and provide some really nice additional value for your APIs as well. They take your Swagger JSON and build you your own API portal out of them. They also have native REST API integration where you can automatically sync up your API to your portal or you can manually upload them.
Here is an example portal they have up to demonstrate how multiple APIs can be hosted and how you see them.
Here is an example of what their documentation for each API looks like. Kind of like Swagger UI++.
You can have multiple swagger instances in a single DW service. The UI, however, does not allow you to point to each of them independently. It's easy enough though to modify index.html to allow the user to select the swagger definitions that you have in the deployment.
Can I use the REST API to filter out users who have not signed in during the last three months?
(I have admin access if that is needed).
Someone correct me if I'm wrong, but from what I know it's not available out of the box. You would probably need to implement a REST plugin module which would get this data from database (or find an existing plugin that does this - I haven't).
There's a page on Atlassian's Confluence that gives you SQLs to get the last login timestamp for a user (and it seems quite up-to-date): https://confluence.atlassian.com/display/JIRAKB/Retrieve+last+login+dates+for+users+from+the+database
Please note that you would have to think about security when developing such a plugin. I have not really considered this, but there might be reasons to include permission restrictions for such a REST resource.
EDIT: I might have found an API (not REST) that exposes login information without the need to query the database (untested): https://developer.atlassian.com/static/javadoc/jira/reference/com/atlassian/jira/bc/security/login/LoginInfo.html
Unfortunately, the JIRA REST API doesn't provide this resource. The latest supported methods can be found on the JIRA REST API Reference Page.
These methods can be tested on your current installation using the JIRA REST API Browser.
The links above contain all of the info you need on the REST API. If you're still interested in using REST, you can always create your own method for retrieving the user list.
Of course, you could use other methods, like SQL, for example. There are a number of plugins available here.
what Tin Can API can do other than storing the state of the agent and how can we retrieve the publicly stored statements from Tin Can API
Thanks in advance
You can do a lot with the Tin Can API (Experience API). The point of the xAPI is to store user experiences, anything from I completed a course to I started watching a video. I've seen or worked on things as simple as using the xAPI to send SCORM tracking to an LRS, to support mobile, tracking sensor data from field exercises, to storing information collected in games and simulations. And the Experience API gives you the ability, like you said, to get data back out in a standard way, to support reporting and evaluation of data.
There are groups working with the Experience API to do interesting things. https://groups.google.com/a/adlnet.gov/forum/#!forum/xapi-design
There is also a spec working group forum where you can get more resources and answers: https://groups.google.com/a/adlnet.gov/forum/#!forum/xapi-spec
There are also resources and articles talking about what you can do with the Experience API. http://www.adlnet.gov/tla/experience-api/
and http://en.wikipedia.org/wiki/Tin_Can_API
There are some open source projects on ADL's GitHub page that also show how you can use the Experience API. https://github.com/adlnet
For sending and retrieving info from an LRS in web browsers there's a JavaScript library: https://github.com/adlnet/xAPIWrapper .. it's been built and minified..you can just include the xapiwrapper.min.js in your page and use the readme examples to get started.
For reporting and querying data you can look at the new project: https://github.com/adlnet/xAPI-Dashboard
There's a starting Java library to make talking to an LRS easier in Java, which could be used for regular Java apps or for Android apps: https://github.com/adlnet/jxapi
They're also starting a JQuery Mobile Plugin: https://github.com/adlnet/xapi-jqm
And even an example of using the Experience API with MedBiquitous and Common Core competencies to identify learner's progress toward becoming competent in some aspect: https://github.com/adlnet/xci
As for your question about getting statements from an LRS, you would just do a GET request to the statements endpoint. The spec currently says that requests must include the Experience API version header: https://github.com/adlnet/xAPI-Spec/blob/master/xAPI.md#62-api-versioning . And you will probably need to authenticate as a client using the LRS. This is generally done by registering on the LRS and getting some sort of credentials. This will vary based on the LRS you use, but they all have instructions on how to use and send the credentials. https://github.com/adlnet/xAPI-Spec/blob/master/xAPI.md#64-security
ADL's hosted example LRS opened up the GET statements endpoint so that people new to the Experience API could hit it and see statements without needing to figure out the request rules: https://lrs.adlnet.gov/xapi/statements