Snipe-it: REST API?

[MattMencel]

Is there an API for this yet? We have an inventory database managed by our Facilities department. I can get data out of their database. If there was a way to import assets via an API of some sort that would be awesome. Entering in hundreds of assets by hand is pretty daunting.

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

[snipe]

Hi Matt - no API yet, but it's definitely something we'd consider. Since many IT people aren't devs, the plan was to work on CSV import first.

[MattMencel]

OK thanks...

[josemanimala]

I can help with this. Let me see what I can come up with.

[mlucas-ue]

Definately would like a CSV or API import option. Have you made any headway?

[jemenake]

I would _love_ to see some API (REST or otherwise) which would enable me to make an iOS app to interface with it. I'm chomping at the bit to be able to use my smartphone to scan barcodes to look up assets.

[taveras]

I love the idea of an API, especially for the simple reason that @jemenake noted, consuming an API would seriously widen the possibilities of how to use Snipe! :)

[oorahduc]

Any updates on having an API? That's the killer for me not being able to use it yet.

[dscherertfm]

An API would be great, and would allow me to further integrate the system into our Intranet without querying the database directly which, to be honest, isn't terrible, it works nicely enough.

[trondvh]

+1 for an API.

[smithkyle]

+1

[fjaeckel]

:+1: this would be an immense help

[kongou-ae]

+1.

[tolleiv]

+1

[vabue]

:+1:

[n8felton]

:+1:

[asmartin]

+1

[ghost]

+1

[tmongero]

+1

[skylarmt]

+1. My company is using Snipe to track e-recycling for compliance reasons, and it would be great if I could build a simple mobile interface for the dock workers to use as they process the e-waste.

[gkid]

+1 especially the ability to update fields and custom fields via API.

[skylarmt]

It looks like there's a little bit of an API already, my browser makes requests like /api/hardware/list?&order=asc&limit=50&offset=0. How much can that API do? It might be good to have some documentation on using it.

[snipe]

It's read-only, and uses your browser session for authentication, so it is not a true rest API in the sense that people here are asking for. That's why it's not documented.

[busilogic]

Trying to get a mobile app going. If I update the data directly into the DB via another frontend, will it cause issues in snipe-it?

[skylarmt]

@busilogic I've made something similar already. SnipeIT is pretty tolerant of missing fields and stuff.

You can find the source for my app here: https://github.com/skylarmt/SnipeITMobileApp. The source for the API I built is here: https://github.com/skylarmt/SnipeITAPI

[snipe]

@busilogic if you're interested in developing a mobile app, please reach out to us. We would love to collaborate with someone who has resources and time for that. (Also note that v3 is very close to being official, so anything you build should be based off that branch)

I would not recommend not using @skylarmt's version, as it interfaces with the database directly and bypasses all of the model level validation that exists for a reason. If their data validation breaks, the entire DB might break.

We'd love to talk about a solid API. We've got a lot of read REST stuff in place now. The question is how we auth, etc.

I'd also love to know why you're interested in a mobile app in the first place. The app is designed responsively, so for the most part a mobile app shouldn't matter.

[asmartin]

What about letting users generate an auth token from within their account in SnipeIT? Said auth token would then have the same permissions as the user.

Is there a list of functions that would be available via the API? Some things I think would be useful:

• add a new asset or accessory
• checkout or checkin an asset or accessory
• create/modify users
• modify custom fields for an asset
• query information about assets (e.g. list of ones Ready to Deploy, all assets of a particular model, etc)

[jurgenschaub]

Hi @snipe! I asked @busilogic to look into this - we'd developed a very very quick-and-dirty audit app to sit on top of our old asset system. The idea being that a tech would say where they are, whose desk they're at, and it would display what assets they _should_ see there. Options to quickly and easily confirm/add/change/delete. Basically an interface optimised for this, without anything else going on. It's certainly not meant as a complete replacement for the current interface. Very limited scope.

[crutchcorn]

@jurgenschaub, even though it would be quick and dirty - open sourcing it for a base work for others (IE me haha) would be awesome. Obviously, removing all specifics to your system (such as keys and such) would allow you to make more or less a template for others, which would be awesome.

Oh, and +1 for REST API. :P

[snipe]

@asmartin We already have some of those API methods, but we have to tie in the API get generation and auth.

[gkid]

+1
I've written a small bash script that curates some system & user info from Mac's. An API would allow me to have the script update Snipe automatically from all of our machines (many of which are in different locations).

[CrewNerd]

+1
I'm starting to work on an RFID solution for tracking boat usage in rowing clubs. With a REST API, I'd be able to write embedded code (in Ruby) in the reader that looks up assets by their RFID tag id and updates their current status.

[slamont]

+1 For a REST API

[freskimo]

+1 REST API

[macjustice]

another +1 for a REST API.

[jonfulton]

+1 for REST API

[RossFMR]

+1 for REST API

[crutchcorn]

For anyone that cares;
I know a lot of people mentioned mobile apps and such, and while I can't help with that;
I am working on a WMI scanner that already works and generates a CSV file that I will make open source and include API calls to snipe-it when finished (along with others, but that's not important).

[erikng]

+1

[happicamper]

Hope that there will be a REST API soon 👍

[satjak]

Maybe someone here might be interested, but i found a way to curl against the current API. https://github.com/satjak/snipe-it-curl

[kmain4]

@satjak But what about creating objects, I want to create objects via POSH at deployment :(

[philmatu]

Unfortunately, I couldn't wait until a full API is available, so I've gone ahead and created an adaptation layer in Python (intended for Amazon Lambda, but will run just about anywhere) that submits HTTP POST messages for now. I've tested on 3.5.1 and will continue to maintain the layer as new versions come out until Snipe releases their official API. Additions/modifications are welcome.

My repository is here: https://github.com/philmatu/snipe-it-api-adapter

[snipe]

FYI, we've begun the process for upgrading to Laravel 5.3, which will make the REST API much easier (using Passport and OAuth, as well as some other stuff). If you're interested in discussing the API requirements, we have a Gitter channel for it here. You can see the (extensive) changes to the existing URL and method structure by comparing the branches here.

To start with, we'll be exposing the read-only aspects of the existing JSON API in a way that will be consumable outside of the logged in session (JWT, tokens, etc), and from there we'll be adding write capabilities.

[snipe]

Continuing this discussion, I am including a discussion from a different thread started by @dmeltzer:

@dmeltzer writes:

Beginning a braindump of what the API might include and how it might look... will be working on this over the next few days.

/api/
 -hardware
    - list [ { GET /api/hardware/list?
        // Do we want to pass filter parameters to this? Or have something like /api/status/3/hardware?
        // What do we want in the full list?
        id,
        asset_tag,
        }, 
        {}, //etc
        {}
    ]
    - show { GET /api/hardware/show/{id}
        asset_tag,
        name,
        serial,
        image_url,
        model_number,
        eol,
        purchase_cost,
        purchase_date,
        notes,
        order_number,
        model_id,
        category_id,
        manufacturer_id,
        status_id,
        location_id, // Default and Current?
        category_id,
        company_id,
        assigned_id,
        assigned_type
        }
    - create { POST to /api/hardware/create/
       Post an object containing some or all of the above view values
       returns object {success: (true|false),  id: id of the created object, errors: json validation errors}
       }
    - edit { PATCH /api/hardware/{id} 
       PATCH an object containing some or all of the above view values
       returns object {success: (true|false),  id: id of the created object, errors: json validation errors}
       }
    - delete? { DELETE /api/hardware/{id}
           DELETE request to above url
           returns object { success: (true|false), json encoded error string on failure.}
       }
    - assigned { GET /api/hardware/{id}/checkout ?
          assigned_type,
          assigned_id,
          assignedTo->name()?  Or should we make that a separate request.

         returns null if available for checkout?
       }
    - checkout { POST /api/hardware/{id}/checkout
           assigned_type,
           assigned_id,
           checkout_date,
           expected_checkin,
           note

           returns object { success: (true|false), json encoded error string on failure.}          
      }
    - checkin { POST /api/hardware/{id}/checkin 
           status_id,
           note,
           checkin_date
      }
  -accessories

My response to this was:

I'm not so much concerned about the endpoints or routes, and I'm writing the documentation on all of that already. It's standard RESTy stuff, so not a lot of mystery there, really.

The bigger question is how people will expect to authenticate with it. API tokens, JWT, OAuth, etc. Does each user get an API token? Is there just a list of app-wide tokens? (If so, how does that affect the expectation that we currently have that there is always a user_id?)

I am approaching this API documentation-first, which means I'm writing up the docs and examples before the API itself gets written, that way we can all have a good idea of how it will work, and any concerns or issues can be raised before all of the coding is done. This will make sure we cover as many use-cases as possible, and includes the benefit of having the documentation already done when the API is done.

You can see why current version of the API docs (still very early stage) here: https://snipe-it.readme.io/v4.0/reference#hardware-list

Please do not use the "Suggest Edits" link on that page at this time, and instead direct your discussion here, so we have one cohesive conversation.

You are also still invited to visit the Snipe-IT API-Talk Gitter Channel and discuss with us there, but any important decisions or information should be moved here.

[philmatu]

@snipe Thank you for posting this information for the upcoming design. As I am already heavily involved in implementing Snipe on a fully automated SNMP/Maintenance/Dispatch environment (set to go out next week as an initial beta test), I'll spend some time in the coming weeks figuring out what works in our environment from a conceptual standpoint and report my observations (and hopefully universally in most environments).

Just as an initial comment, I'm finding that when managing tens of thousands of assets, bulk modifications absolutely need to be supported, API calls are only so fast. When modifying thousands of assets simultaneously, this type of call would bog down any PHP frontend and improperly sized database, meaning that the API also should be logically separated from the UI layer, preferably running in its own process space (in my case, a completely separate AWS instance) and have some sort of db resource limit (manageable via a separate DB user on MySQL). It's been a long time since I've done any useful coding in PHP, but Laravel seems like it uses a traditional MVC architecture where this doesn't seem like a lot of additional work to accomplish. As my resources move towards user support, I might be able to contribute some of the work towards getting this API working correctly to the finalized draft that you're currently working on.

As for authentication, OAuth seems like the best solution for authentication these days, although I'd logically separate the OAuth implementation from a generic Authentication layer/interface that can accept multiple types of authentication. I can see myself making local calls on the API server directly to modify assets based on hourly data pulls that our other automated processes gather here and that wouldn't necessarily need any authentication (so maybe a local cli authenticator).

[snipe]

Hi @philmatu - thanks for the feedback.

It's unlikely that we'd build-in the need/capacity for the API to live on a separate machine/process space any time soon. It simply goes outside the scope of what most people need, and would add a layer of complexity that would add to an already overburdened support crew. You can already batch edit through the UI, and I'm sure we'll replicate that functionality via the API over time, but that type of infrastructure is just so far beyond what 99.999% of our users need, I can't see spending the engineering time on it. PHP is fast, and so is MySQL, so it should be able to handle most of what you throw at it under normal circumstances. As you discover more of what your needs are, you're certainly welcome to keep me in the loop and see is that's something that makes sense for the project though. If you wanted to suss out a way to enable that as a purely optional feature that could be completely disabled and wouldn't add unnecessary coding overhead to implement, we might consider merging a PR for that.

Our minds are always open, but we do have to keep the needs of the many in front of the needs of the few, as I'm sure you can understand.

As for modifying assets hourly via command line, we already have a cli importer that can update assets, so I'm sure you could probably work with that for now, as it doesn't require any authentication. Any additional command line tools will likely come after the API.

[snipe]

@philmatu What exactly are you updating in the thousands of assets range? Thousands of updates at a time should be no biggie for PHP and MySQL, if the API call made sense (for example, a PATCH instead of a PUT, with a transaction or queue behind it, or something like that, depending on what you're doing.)

[philmatu]

@snipe I understand that most people wouldn't need the API/UI separated. But I will comment saying that usually a good design separates the UI and backend via an API platform. This uncouples the UI from the backend and allows development to proceed in separate threads by experts of their field. It takes a little more effort up front to implement this type of design, but it provides a much more maintainable product at the end of the day regardless of if all the components are run on a single server or distributed out (most users would use a single server, obviously). I've personally been burned by coupling a backend to the frontend in the past and veer away from this type of design now. As an example, another project that has moved in this direction from a highly coupled core is Icinga, it's a slow and painful process (from what I've seen), but it has improved vastly as a result (with additional targeted UIs becoming available by other developers).

As for your suggestion of using the existing import functionality, I saw something about that, but I suspected it was for a single time import. I'll look into using this functionality to complete mass updates more quickly.

I will admit that PHP and MySQL are very quick, but after managing a MySQL database (not related to this) with 20 billion records (and growing daily), MySQL does bog down and needs some assistance with caching, indexing, etc. I fully expect our asset management DB to grow rapidly, although I can see hundreds of thousands of rows in a few select tables, like in maintenance actions (which I suspect we will see 500-1000 daily with 5 years of history storage required). I've looked at the indexing on those tables and I don't anticipate any major issues.

Like I've said before, I'll be happy to help where I can and will update the Glitter Channel once I have a better idea of what we're going to be using (and seeing) daily.

[snipe]

But I will comment saying that usually a good design separates the UI and backend via an API platform. This uncouples the UI from the backend and allows development to proceed in separate threads by experts of their field.

I honestly don't know what you're trying to convey here, other than to unnecessarily explain to me how modern web apps are supposed to be built. I've been in the industry for 20 years. I may have architected an application or two.

Microservices and complex, multi-system abstraction between layers makes a lot of sense for some applications, less so for others.

Most of our users can barely get one web server running, let alone one to handle the API and one to handle the UI - and frankly, it's serious overkill for just about everyone except perhaps you. Premature optimization is the root of all evil, and I look forward to hearing what your actual needs end up being.

I'm not particularly interested in having an architecture debate in an API needs thread at all, but at the very least not until I know what you're specifically trying to accomplish.

The point of this thread is to discuss the highest priority endpoints based on most urgent user needs, and to discuss the authentication methods they will be using so that we can make sure they're accounted for. Let's keep it on track for that for now.

[thinkl33t]

If you'd like some use cases / user stories for API functionality:

1. We're using the current 'unofficial' API to generate labels for our sticker printer automatically for new assets, which works fairly well - we run ./print-asset-label.py <asset tag> to generate and print a label directly to the dymo from a templated SVG.
2. We would like to import our list of windows licenses, which is keyed on the machine's asset tag. Unfortunately we cant find a way of programmatically doing this, as windows licenses need to be checked out to a machine, not a user.
3. We would like to give our users to ability to check out assets in a self-service manner though an IRC bot, based on the asset tag. We can write the bot ourselves, but would need a way to check out an asset from the API based on asset number.

Regarding authentication / authorization, Personally I'd like to see something simplistic, like a 2 tier API key per user, sent in a header:

• Read only API key generated on demand for all users (useful for case 1 above)
• Read / Write API key generated on demand for users with write access (useful for case 2 above)

[snipe]

Thanks @thinkl33t - that's very helpful!

[snipe]

Just another quick update - the API is moving along pretty well. I've been keeping the docs and the live API explorer updated as we go, so you can take a look at what we have:

https://snipe-it.readme.io/v4.0/reference#api-overview

If you click on any of the endpoints in the side-nav, you can actually test a live API (coming from the develop demo), so feel free to play around. If you wreck it too badly, we can easily reset it..

Right now we've got basic CRUD model stuff working for:

• Assets (ignore all the gross HTML - still cleaning up with Transformers)
• Manufacturers
• Suppliers
• Users (partial)
• Companies
• Components
• Status Labels
• Models
• Categories
• Locations
• Accessories

Additionally, about 1/3 of the Web UI on the develop branch is consuming the new APIs already, with more on the way. We've still got some more javascript work to do before some of the pieces of the Web UI are less broken (specifically most of the Ajax stuff), but the code we'll end up with will be easier to maintain anyway, so everybody wins.

I would NOT recommend anyone actually use the develop branch right now, as it's very volatile right now, but didn't want to keep people in the dark about our progress. Things are moving very quickly, so check back often!

[ghost]

I have checked the "Asset acceptance" in my super admin Settings.
But on Assigning the asset to the user, there is no response through email that asset was assigned to particular user. Already when i have assigned 'ready to deploy' option to the user, still i am not getting mail from the Snipe IT to the user email ID.

Please inform further settings what should do for the email processing to the user and also asset acceptance signature by the user.
please inform this as soon as possible.
Thank you.

[timwsuqld]

@snipe Are there plans to bring the License's into the API as well?

[erikng]

Does this mean v4.0 release is right around the corner?

[snipe]

It means the API is done :)