I have undertaking a master thesis project that uses the openapi.yaml files to auto generate test for REST-api web-services - This has lead me to host a local instance of gitlab, so that I can run the tool I am working on, on gitlab. For that to happen I need the .yaml files containing the documentation for the API calls. Such files are found within in the gitlab source-code, but the call does not seem to work.
Some calls work, namely:
http://localhost/api/v4/version
http://localhost/api/v4/users
http://localhost/api/v4/projects
http://localhost/api/v4/groups
all returns meaningful JSON.
the problem is that a lot of the calls within the documentation does not work (returns a "404 not found"), namely:
http://localhost/api/v4/metadata
http://localhost/api/v4/projects/{id}/access_tokens
and more calls specified in the documentation.
The problem is that a lot of the calls that work are not documented (all of the above except the 'version' call). I have really tried to look for an alternative openapi.yaml files, but with little success and I am also puzzled to why the one left in the actual source-code does not contain meaningful documentation. Have I overlooked something? I am currently using postman and providing a sudo authentication-token.
Thanks in advance - I must surely have overlooked something!
Currently I have tried to look for an alternative openapi.yaml both by googling and be browsing swaggerhub.com. I Have look at the documentation pages for gitlab, but I have not found anything I did not already have.
Unfortunately, at this time of writing, GitLab does not provide an OpenAPI spec for all of its API. Only a very small part of the API is documented in openapi.yml. There is an open issue that is tracking this improvement.
For now, the online API docs are going to be your best source of information available on using the GitLab API.
As for your problem of getting 404 responses, the most common cause of this is that the credentials you are using do not have permissions to the project/feature you are trying to access or you are not using a proper authentication method. Also keep in mind some features of the API require an appropriate license entitlement.
Related
I have a device for which I am implementing an HTTP API and defining it via OpenAPI 3.0.
The following paths are defined:
/scan/inventory/start
/scan/location/start
/scan/direction/start
This API is designed to run on various devices, but not all of them implement the location or direction feature, but all do implement the inventory feature. The available features can be queried by GETing the /scan path.
For a device that does not support location my team has been waffling on the error code to return if someone attempts to use it. We want to provide useful feedback when this happens, so 404 seems ruled out, especially since the path is documented in our API. After reading and re-reading RFC-7231 and various summaries of it, 501 or 403 seemed like good choices.
At first, "501 Not Implemented" seemed like a good choice, but the 5XX class of errors seems to suggest a more serious server error.
Since we want to provide feedback, "403 Forbidden" seems good and puts the onus on the client for accessing a bad path.
I'm sure part of the problem is that we're attempting to use a specification (HTTP) that was not necessarily designed for arbitrary APIs.
What would you suggest we do?
This is a pretty straightforward 404.
The 404 (Not Found) status code indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists.
403 isn't right, since that indicates that the user isn't "authorized" to access that resource. It implies that the issue lies on the client side. But in this case there simply is no resource.
501 isn't right, since that "indicates that the server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource." In this case the server has no problem supporting the request, it's just that the resource doesn't exist.
Note that "server" refers to the web server. The issue isn't whether or not your application as a whole supports some bit of functionality, it's whether the web server is capable of handling the HTTP request it was sent. It's not appropriate to use HTTP status codes to indicate that kind of high-level application state.
Also note that the status code isn't just a private contract between your application and its users. All actors in the web stack—loggers, intermediate caches, browsers, etc.—might change their behavior depending on the status code. That's why it's important to reserve things like 5xx for actual server errors.
To summarize, since the resource at that URI doesn't exist, the best way to provide useful feedback is to return a 404. If you want to distinguish between features that are never supported and those that are simply unsupported for that device you should use a mechanism other than the status code. Fortunately you're off to a good start by listing the available features at /scan.
I'm a new to RESTful API's and sort of developing my first one at the moment for a mobile application to be followed. I have a question regarding API versions and how to manage/tackle them.
At this moment, my API 'version' is a directory named v<version_name> in which my API class resides. In that directory, I have resources that the API and REST client needs in another directory named include. So the structure is as follows: example.com/api/v0.2/method_name/ and on .htaccess, I'm making sure that everything that follows the API version (hardcoded in the .htaccess file, is saved in a query string parameter).
I'm not sure if it is the right approach for a live application as it requires manually changing the URL endpoints at clients' ends, too. So my questions are:
Is this the right approach to API versioning?
If it is and I keep it, how do I deal with outdated URL's. Say for instance the app is live and I update the API to v0.3 but the client who have the app installed would be accessing v0.2 and getting a 404 response code back?
Is there more elegant solution out there? It must be.
Edit: there are some resources that reside outside of the api folder itself, in the root include folder so to speak.
Edit 2: My API is targeted to be consumed by mobile applications and is not publicly consumable.
While I think these questions are primarily opinion-based, I will have a go...
I think it is a valid approach, and I've seen others use it,
including Microsoft.
When it is necessary to outdate an API, you could give a 404
back with an explanation that the new API is at the new address.
HOWEVER it is usually a bad idea to just retire an API version; you
would at least have to give client developers enough time to switch
to the new API before retiring the old, if at all.
A more elegant solution would be to just keep the API at one
address, and update that as necessary, and add to it rather than
replace whenever possible. Keep supporting outdated functions for as
long as possible and have open communication to client developers
about when a certain method will no longer work.
Just my opinion, do with it what you will...
In a customized Login Module I've developed for my application server (GlassFish 3.1.2.2), I'm using the following syntax to obtain the HttpServletRequest:
PolicyContext.getContext(HttpServletRequest.class.getName())
And it works fine.
But now I'm configuring the server to use only HTTPS and the same instruction returns null.
I guess this is a security restriction, but I'm not sure what needs to be changed in order to solve this issue (server.policy?).
To put this under context, I need to record the IP address of all login attempts, valid and invalid, and getting the request in the module seemed the most obvious solution.
Can someone help me to figure out a solution?
I can't help you directly with your question, but you may want to note that PolicyContext is a JACC class. It's spec'ed to work inside JACC policy providers. You may want to look at an article I wrote that explains this more in depth.
There is thus no specific guarantee that obtaining the HttpServletRequest works from inside a GlassFish proprietary login module, although I indeed have seen people using this more often and it typically works. The fact that it does not work when you switch to https sounds more like a bug or oversight to me than any specific security restriction.
A workaround for you could be to rewrite your login module as a Java EE standard auth module using JASPIC. I've also written an article about that subject which you could use for reference. In JASPIC you explicitly have access to the HttpServletRequest.
hello all i havent managed to find this elsewhere here nor in the old GAS product forum so here goes:
i am writing a simple client javascript which queries various APIs. when it comes to querying a certain GAS script i have set up to access gmail, i understand i am supposed to serve its data through JSONP. the client script dynamically injects a SCRIPT tag and should normally handle this "response" as script. except whenever the response contains html, requesting the user to grant permissions. in this case this HTML goes into the SCRIPT raising syntax error with MIME type mismatch.
researching this problem i was led to believe the solution lies somewhere around redirecting the user to this page always before every call. so my question is, where can i find best practice regarding this issue?
Unfortunately there isn't a full solution for detecting and granting authorizations to scripts used in JSONP requests. I've seen workarounds where an application first prompts the users to visit the web app's URL, so that they can grant authorization, before allowing them to use the JSONP portion of the application.
Currently Azure Websites don't allow custom SSL certificates, but they have wildcard SSL enabled for the *.azurewebsites.net domain. I need a secure login form for my web app, but with no custom SSL, it appears that I'm SOL.
Is there any kind of workaround for this? Would it be possible somehow to have a login form at https://mydomain.azurewebsites.net that creates a forms authentication ticket that will then work at http://mydomain.com?
Couple of months ago I had exactly the same problem i.e. application was built on Azure Websites, had to run on custom domain other than *.azurewebsites.net and had to allow secure login process.
Workaround for that we used was to embed an iframe (using secure protocol and .azurewebsites.net domain name e.g. https://oursite.azurewebsites.net/login) into non-secure page on custom domain (e.g. http://mysite.com/login). And entire login process was performed in the iframe.
There is one thing which you should be aware of, namely, lots of customers checks whether the page where they provide their credentials was using secure connection or not. In our case, secure iframe in non-secure page was causing lots of customer complains. Workaround for that problem was to put a message confirming that the login process uses secure connection. The message made some improvements, however, still certain number of customers complains remained.
I hope that will help.
This isn't really an answer to your question, but Microsoft are very aware that custom mapped SSL to websites is one of the most requested features for Azure websites and they have said they are working on it.
Scott Hanselman himself confirms it here
In the meantime, Tom's answer is a perfectly valid workaround.
One thing I would be very wary of though is with something Tom brings up: the security warning that the browser will present. You'd be amazed how many people freak out when they see that message and don't go any further! We have a fairly active ecommerce site and there have been occasions where we have accidentally used a none secure image path on an SSL page and we have always received emails from customers asking if our site has been hacked or similar!
The disclaimer that Tom mentions is a good idea, but I think it will still put some people off.
I am working directly with the WAWS team right now to produce some public guidance for this. A GitHub repository with the requirements is currently being evaluated by the team (I sent it over to them literally 1 hour ago). Hopefully, the solution will be approved and made public within a few weeks.
I can say this - the workaround won't be fully supported or much custom guidance given on its usage aside from the repository and accompanying documentation. SSL is, literally, the #1 priority for the product, and hundreds of people are working insane hours to make it happen for everyone. This workaround should also be considered temporary, as you'll no longer need it once the full SSL functionality is launched.