{"id":24122250,"url":"https://github.com/tlinden/apid","last_synced_at":"2025-09-07T07:38:45.009Z","repository":{"id":22101137,"uuid":"25431378","full_name":"TLINDEN/apid","owner":"TLINDEN","description":"Generic REST API Daemon","archived":false,"fork":false,"pushed_at":"2017-02-24T08:38:11.000Z","size":132,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-09-07T07:38:44.111Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://search.cpan.org/dist/WWW-REST-Apid/","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TLINDEN.png","metadata":{"files":{"readme":"README","changelog":"Changelog","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-10-19T15:43:48.000Z","updated_at":"2020-11-25T21:30:22.000Z","dependencies_parsed_at":"2022-07-25T09:01:59.092Z","dependency_job_id":null,"html_url":"https://github.com/TLINDEN/apid","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TLINDEN/apid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TLINDEN%2Fapid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TLINDEN%2Fapid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TLINDEN%2Fapid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TLINDEN%2Fapid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TLINDEN","download_url":"https://codeload.github.com/TLINDEN/apid/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TLINDEN%2Fapid/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274010097,"owners_count":25206763,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-11T11:39:23.723Z","updated_at":"2025-09-07T07:38:44.975Z","avatar_url":"https://github.com/TLINDEN.png","language":"Perl","readme":"NAME\n    apid - Generic REST API Daemon\n\nSYNOPSIS\n     Usage: apid [ -c file ] [ -f ] { command }\n      -c file         Specify configuration file (instead of apid.conf)\n      -f              Run in the foreground (don't detach)\n\n     Possible commands are:\n      start      Starts a new apid if there isn't one running already\n      stop       Stops a running apid\n      reload     Causes a running apid to reload it's config file.\n                 Starts a new one if none is running.\n      restart    Stops a running apid if one is running. Starts a new one.\n      check      Check the configuration file and report the daemon state\n      help       Display this usage info\n      version    Display the version of apid\n      debug      Starts a new apid in the foreground\n\nDESCRIPTION\n    apid is a generic http(s) daemon which can be used to provide a RESTful\n    web service in front of something which isn't already web aware. If you\n    already have some application server or website with a service running,\n    apid is of no use for you. However, if there's some arcane, weird or\n    just old computing system which is accessible by perl you want to make\n    available online as a web service, then apid might be a solution.\n\n    To use apid, you have to write a perl script which maps uris to\n    handlers, so you're totally free in what you want to achieve and how to\n    do it.\n\nFEATURES\n    *   supports http and https.\n\n    *   authentication via POST vars or basic authentication\n\n    *   decorators which you can use to enable authentication or input\n        validation per uri.\n\n    *   automatically converts incoming data (post vars, json post or query\n        string) to a perl structure for easy access. Handlers return perl\n        structures which will be converted automatically to json as well.\n\nCONFIGURATION\n    A config file is required for apid to work. The format is very simple,\n    one option per line, the value separated by an equal sign. Empty lines\n    or lines preceeded with '# are ignored.\n\n    Possible parameters:\n\n     host       = localhost\n     port       = 4433\n     map        = my.pm\n     apiname    = My API\n     apiversion = 0.0.1\n     sslcrt     = server.crt\n     sslkey     = server.key\n\n    If sslkey or sslcrt is omitted, apid will speak http, otherwise https.\n    You can configure more aspects of ssl by using IO::Socket::SSL-new()\u003e\n    parameters.\n\nMAP SCRIPT\n    The map script, in the config specified with the map parameter, controls\n    the behavior of apid. In its simplest form it only contains a couple of\n    handlers, here an example:\n\n     get '/date' =\u003e sub {\n       my $date = scalar localtime();\n       return { date =\u003e $date };\n     };\n\n    Now, start apid:\n\n     apid -c my.conf -f start\n\n    And access the api function:\n\n     % curl http://localhost:8080/date\n     {\"date\":\"Wed Oct 22 20:29:50 2014\"}\n\n    Can't be easier.\n\n  AUTHENTICATION\n    To use authentication, you have to implement a login function and you\n    have to tell apid which kind of auth you want.\n\n    Full example:\n\n     use Authen::Simple::LDAP;\n\n     auth basic =\u003e 'my api';\n\n     implement login =\u003e sub {\n       my($user, $pass) = @_;\n\n       my $ldap = Authen::Simple::LDAP-\u003enew( \n         host    =\u003e 'ldap.company.com',\n         basedn  =\u003e 'ou=People,dc=company,dc=net'\n       );\n\n       if ( $ldap-\u003eauthenticate( $user, $pass ) ) {\n         return 1; # ok\n       }\n\n       return 0; # fail\n     };\n\n     request login;\n     get '/date' =\u003e sub {\n       my $date = scalar localtime();\n       return { date =\u003e $date };\n     };\n\n    In this case we are using basic authentication which is backed by LDAP.\n    If successfull, apid will return a cookie with a session id, which can\n    be used in subsequent requests. However, with basic authentication this\n    is optional, you may also leave the session cookie and just put the auth\n    data into every request.\n\n   ENABLE BASIC AUTHENTICATION\n     auth basic =\u003e 'my api';\n\n    The second parameter to the auth decorator is the realm.\n\n   ENABLE POST/REDIRECT AUTHENTICATION\n     auth redirect =\u003e '/login';\n\n    The second parameter to the auth decorator is the login uri.\n\n    In this mode, an unauthenticated user is being redirected to the\n    specified uri, where the user has to POST the username and password,\n    which can either be posted as a JSON string or as query string.\n    Examples:\n\n    Post auth data as JSON string:\n\n     curl -d \"{\\\"user\\\":{\\\"me\\\":\\\"mypass\\\"}}\" http://localhost:8080/login\n\n    Post auth data directly:\n\n     curl -d \"user=me\u0026pass=mypass\" http://localhost:8080/login\n\n    It is also possible to use a query string\n\n     curl \"http://localhost:8080/login?user=me\u0026pass=mypass\"\n\n   LOGIN IMPLEMENTATION\n    In either case, you must implement the actual login function by using\n    the 'implement' decorator:\n\n     implement login =\u003e sub { my($user, $pass) = @_; ... };\n\n    Inside, you can use whatever you want. I'd suggest using one of the\n    Authen::Simple submodules.\n\n    The login handler must return true to indicate authentication was\n    successfull.\n\n   AUTHENTICATION DECORATOR\n    To enable authentication for a specific uri, add the following decorator\n    in front of it:\n\n     request login;\n     get '/date' =\u003e sub { .. };\n\n    This has to be done for every uri handler. If you leave the decorator\n    for a handler it can be accessed without authentication. Example:\n\n     request login;\n     get '/date'   =\u003e sub { .. };\n\n     get '/uptime' =\u003e sub { .. };\n\n     request login;\n     get '/vmstat' =\u003e sub { .. };\n\n    In this example, the uris /data and /vmstat require authentication while\n    /uptime can be accessed by everyone.\n\n  URI MAPPING\n    There's only one decorator call you use to map an uri to a handler: get.\n    Apid doesn't distinguish between POST, PUT, DELETE or GET requests. So,\n    however the uri have been called, your handler will always be called. If\n    you need to distinguish between the various request types, you have to\n    do it yourself in your handler.\n\n     get '/some/uri' =\u003e sub { my $data = shift; ... return {}; };\n\n    The handler gets passed the submitted data as its first and only\n    parameter, if present. The data is always a perl structure.\n\n    Apid expects the handler to return a perl structure as well, which will\n    be converted to JSON and returned to the client.\n\n    There are a couple of variables which are available to each handler:\n\n    $req\n        This is a standard HTTP::Request object. In addition, if\n        authentication was enabled, it contains the username of the\n        authenticated client:\n\n         $req-\u003e{user}\n\n    $res\n        This is a standard HTTP::Response object. You may modify the HTTP\n        return code or add additional headers to the response as you please.\n\n    %cfg\n        This is a hash containing all options of the configuration file. It\n        has been parsed by Config::General.\n\n  INPUT VALIDATION\n    Apid can validate input data automatically by using\n    Data::Validate::Struct. To enable it, use the validate decorator:\n\n     request validate =\u003e { expression =\u003e 'text' };\n     get '/ps/search' =\u003e sub {\n       my $data = shift;\n       return \u0026ps2a($data-\u003e{expression});\n     };\n\n    The parameter to the decorator is the validator struct required by\n    Data::Validate::Struct. Please refer to the documentation there for\n    details.\n\n    If input validation fails, apid will return an error message as JSON and\n    HTTP response code 403.\n\n  AUTOMATIC DOCUMENTATION\n    Usually you'll want to write the documentation for your API yourself.\n    For the lazy ones, there's a documentation decorator, which you can use\n    to generate it.\n\n     request doc =\u003e 'some text';\n     get '/some/uri' =\u003e sub { .. };\n\n    If apid encounters one or more documentation decorators it generates a\n    documentation which is available at /doc/.\n\n    Beware, that this documentation is very basic, however it at least\n    explains if the uri requires authentication, what kind or input it\n    expects (if validation were enabled) and if authentication is required.\n\nHELPFUL CURL COMMANDS FOR TESTING\n    auth to url with login requested:\n\n     curl -c cookies -b cookies -k -v --user USER:PASS https://localhost:4443/foo/bar\n\n    access url when auth ok:\n\n     curl -c cookies -b cookies -k -v https://localhost:4443/foo/bar\n\n    post query data:\n\n     curl -k -v -d \"name=foo\u0026year=2014\" https://localhost:4443/foo/bar\n\n    post json data:\n\n     curl -k -v -d \"{\\\"user\\\":{\\\"name\\\":\\\"foo\\\"}}\" https://localhost:4443/foo/bar\n\n    post json file 'body.json':\n\n     curl -k -v -H \"Content-Type: application/json\" -d @body.json https://localhost:4443/foo/bar\n\n    post data as query string:\n\n     curl -k -v -d \"https://localhost:4443/foo/bar?name=hans\u0026age=2014\"\n\n    get json data:\n\n     curl -k -v -d https://localhost:4443/foo/bar\n\nAUTHOR\n    T.v.Dein \u003ctlinden@cpan.org\u003e\n\nBUGS\n    Report bugs to\n    http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-REST-Apid\n\nSEE ALSO\n    WWW::REST::Apid HTTP::Daemon HTTP::Daemon::SSL Daemon::Generic\n    Config::General Data::Validate::Struct\n\nCOPYRIGHT\n    Copyright (c) 2014 by T.v.Dein \u003ctlinden@cpan.org\u003e. All rights reserved.\n\nLICENSE\n    This program is free software; you can redistribute it and/or modify it\n    under the same terms as Perl itself.\n\nVERSION\n    apid Version 0.06.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftlinden%2Fapid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftlinden%2Fapid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftlinden%2Fapid/lists"}