1HIFORMAT: 1A 2 3# OpenGrok 4 5OpenGrok RESTful API documentation. The following endpoints are accessible under `/api/v1` with the exception of `/metrics`. 6 7Besides `/suggester`, `/search` and `/metrics` endpoints, everything is accessible from `localhost` only 8unless authentication bearer tokens are configured in the web application and used via the 'Authorization' HTTP header 9(within HTTPS connection). 10 11Some of the APIs are asynchronous. They return status code 202 (Accepted) and a Location header that contains the URL 12for the status endpoint to check for the result of the API call. Once the status API returns result other than 202, 13the client should issue DELETE request to this URL to clean up server resources. 14 15## Annotation [/annotation{?path}] 16 17### Get annotation for a file [GET] 18 19+ Parameters 20 + path (string) - path of file, relative to source root 21 22+ Response 200 (application/json) 23 + Body 24 25 [ 26 { 27 "revision": "c55d5891", 28 "author": "Adam Hornáček", 29 "description": "changeset: c55d5891\nsummary: Rewrite README.txt to use markdown syntax\nuser: Adam Hornáček <adam.hornacek@oracle.com>\ndate: Wed Aug 30 17:42:12 CEST 2017", 30 "version": "1/15" 31 }, 32 { 33 "revision": "5e0c6b22", 34 "author": "Vladimir Kotal", 35 "description": "changeset: 5e0c6b22\nsummary: bump year\nuser: Vladimir Kotal <vlada@devnull.cz>\ndate: Thu Jul 18 14:43:01 CEST 2019", 36 "version": "14/15" 37 } 38 ] 39 40## Authorization framework reload [/configuration/authorization/reload] 41 42### reloads authorization framework [POST] 43 44This is asynchronous API endpoint. 45 46+ Request (application/text) 47 48+ Response 204 49 50## Configuration [/configuration] 51 52### return XML representation of configuration [GET] 53 54+ Response 200 (application/xml) 55 + Body 56 57 ``` 58 <?xml version="1.0" encoding="UTF-8"?> 59 <java version="1.8.0_172" class="java.beans.XMLDecoder"> 60 <object class="org.opengrok.indexer.configuration.Configuration" id="Configuration0"> 61 <void property="allowLeadingWildcard"> 62 <boolean>true</boolean> 63 </void> 64 </object> 65 </java> 66 ``` 67 68### sets configuration from XML representation [PUT] 69 70This is asynchronous API endpoint. 71 72+ Request (application/xml) 73 + Body 74 75 ``` 76 <?xml version="1.0" encoding="UTF-8"?> 77 <java version="1.8.0_172" class="java.beans.XMLDecoder"> 78 <object class="org.opengrok.indexer.configuration.Configuration" id="Configuration0"> 79 <void property="allowLeadingWildcard"> 80 <boolean>true</boolean> 81 </void> 82 </object> 83 </java> 84 ``` 85 86+ Response 201 (application/json) 87 88## Configuration field [/configuration/{field}{?reindex}] 89 90### returns specific configuration field [GET] 91 92+ Response 200 (application/json) 93 94### sets specific configuration field [PUT] 95 96This is asynchronous API endpoint. 97 98+ Parameters 99 + reindex (boolean) - specifies if the underlying data were also reindexed (refreshes some searchers and additional data structures) 100 101+ Request (application/text) 102 103 string value of the field to set 104 105+ Response 204 106 107## File content [/file/content{?path}] 108 109### get file content [GET] 110 111Honors the `Accept` header. If the value of the header is set to `text/plain` 112and there is a document in the index that has the genre detected as plain text, 113the contents of the document will be returned. If the document is not found, 114HTTP error 404 will be returned. If the genre of the document is not plain text, 115HTTP error 406 will be returned. 116Alternatively, one can use the `application/octet-stream` value of the header 117which bypasses the document and genre check. 118The `Content-type` header of the reply will be set accordingly. 119 120+ Parameters 121 + path (string) - path of file, relative to source root 122 123+ Response 200 (text/plain) 124 + Body 125 126 foo 127 bar 128 129+ Response 200 130 131## File genre [/file/genre{?path}] 132 133### get file genre [GET] 134 135+ Parameters 136 + path (string) - path of file, relative to source root 137 138+ Response 200 (text/plain) 139 + Body 140 141 genre as identified by analyzer, could be PLAIN, XREFABLE, IMAGE, DATA, HTML 142 143## History [/history{?path,withFiles,start,max}] 144 145### get history entries [GET] 146 147+ Parameters 148 + path (string) - path of file/directory to get history for, relative to source root 149 + withFiles (optional, boolean) - whether to include list of files 150 + start (optional, int) - start index 151 + max (optional, int) - number of entries to get (default value 1000) 152 153+ Response 200 (application/json) 154 + Body 155 156 { 157 "entries": [ 158 { 159 "revision": "86b0ab6b", 160 "date": 1565163646000, 161 "author": "Adam Hornacek <adam.hornacek@oracle.com>", 162 "tags": null, 163 "message": "Try to use mvnw in CI", 164 "files": [ 165 "/opengrok/docker/README.md" 166 ] 167 }, 168 { 169 "revision": "a391bead", 170 "date": 1564745178000, 171 "author": "Adam Hornacek <adam.hornacek@oracle.com>", 172 "tags": null, 173 "message": "Fix docker readme typo", 174 "files": [ 175 "/opengrok/docker/README.md" 176 ] 177 }, 178 { 179 "revision": "33551f14", 180 "date": 1563531391000, 181 "author": "Vladimir Kotal <vlada@devnull.cz>", 182 "tags": "1.3.0, 1.2.25, 1.2.24", 183 "message": "document docker-compose", 184 "files": [ 185 "/opengrok/docker/README.md" 186 ] 187 } 188 ], 189 "start": 5, 190 "count": 3, 191 "total": 24 192 } 193 194 195## Include files reload [/system/includes/reload] 196 197### reloads all include files for web application [PUT] 198 199+ Response 204 200 201## Get last index time [/system/indextime] 202 203The time is in the ISO 8601 format in UTC time zone. 204 205### Retrieve last index time [GET] 206 207+ Response 200 (application/json) 208 + Body 209 210 "2021-02-15T16:39:16.409+00:00" 211 212## Messages [/messages{?tag}] 213 214### adds message to a system [POST] 215 216Usable values for `messageLevel` are: `success`, `info`, `warning`, `error`. 217This will affect CSS class of the displayed message, leading to different coloring. 218 219The values in the `tags` list can be: `main` (special value for top level message in the whole web application), 220project name and project group name. 221 222The format of `duration` is the same as Java's java.time.Duration class, 223see https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html#parse-java.lang.CharSequence- 224 225+ Request (application/json) 226 227 { 228 "tags": ["main"], 229 "messageLevel": "info", 230 "text":"test message", 231 "duration":"PT10M" 232 } 233 234+ Response 201 235 236### deletes messages with specified tag [DELETE] 237 238+ Request (text/plain) 239 240 string value of the message text - only messages with the text (and specified tag) will be deleted 241 242+ Parameters 243 + tag (string) - tag 244 245+ Response 204 246 247### returns all messages with specified tag [GET] 248 249+ Parameters 250 + tag (string) - tag 251 252+ Response 200 (application/json) 253 254 [ 255 { 256 "expired": false, 257 "created": "2019-01-23 20:39:31 CET", 258 "tags": [ 259 "main" 260 ], 261 "expiration": "2019-01-23 20:49:31 CET", 262 "cssClass": "class", 263 "text": "test message" 264 } 265 ] 266 267## Monitoring [/metrics/prometheus] 268 269### retrieves web application metrics in Prometheus format [GET] 270 271+ Response 200 (text/plain) 272 273## Path descriptions [/system/pathdesc] 274 275### updates path descriptions for web application [POST] 276 277This will refresh the path descriptions. The web application will store 278the descriptions in a file under data root so it is not necessary to load the path 279descriptions manually after each web application redeploy. 280 281The paths are relative to source root, starting with /. 282 283+ Request (application/json) 284 + Body 285 286 [ 287 {"path": "/foo", "description": "foo foo"}, 288 {"path": "/bar", "description": "bar"} 289 ] 290 291 292+ Response 204 293 294## Projects [/projects] 295 296For all entry points that modify web application configuration it is worth noting that 297the configuration has to be retrieved and stored on disk (using the configuration specific 298entry points) in order to be persistent (e.g. in case of application server restart or 299web application redeploy). 300 301### returns a list of all projects [GET] 302 303+ Response 200 (application/json) 304 + Body 305 306 ["foo","bar"] 307 308### add project [POST] 309 310This will merely add the project and its repositories to the web application configuration. 311The project will not be searchable (and thus appear in the UI) until it is indexed. 312 313+ Request (text/plain) 314 + Body 315 316 text/plain name of the project 317 318+ Response 201 319 320## Project management [/projects/{project}] 321 322### delete project [DELETE] 323 324This will remove the project and its repositories from the web application configuration. 325It will also delete project specific data such as index, cross reference pages, history index 326and suggester data. 327 328+ Response 204 329 330## Project data management [/projects/{project}/data] 331 332### delete project index data [DELETE] 333 334This will delete project index data but keep the project in web application configuration so that 335can be indexed from scratch. 336The project data (whatever is the project's directory under source root) will be left intact. 337This will also mark the project as not indexed. 338 339+ Response 204 340 341## Project history cache management [/projects/{project}/historycache] 342 343### delete history cache for a project [DELETE] 344 345This will delete history cache for a project. 346 347+ Response 204 348 349## Project metadata management [/projects/{project}/indexed] 350 351This entry point is used by the Indexer once it finishes indexing given project. 352 353### marks project as indexed [PUT] 354 355This is asynchronous API endpoint. 356 357+ Request (text/plain) 358 + Body 359 360 empty 361 362+ Response 204 363 364## Project index files [/projects/{project}/files] 365 366### Get a list of files tracked by the index database for given project [GET] 367 368+ Response 200 (application/json) 369 + Body 370 371 ["/project/foo.txt","/project/bar.txt"] 372 373## Project metadata [/projects/{project}/property/{propertyname}] 374 375The list of per project properties can be found on 376https://github.com/oracle/opengrok/wiki/Per-project-configuration#properties 377 378### sets property value for the project [PUT] 379 380+ Request 381 + Body 382 383 body – string representation of the value to set 384 385+ Response 204 386 387### returns the property value [GET] 388 389+ Response 200 (application/json) 390 391## Project repositories [/projects/{project}/repositories] 392 393### returns a list of repositories for the specified project [GET] 394 395Native path separators (of the system running the service) 396will be used for repository paths. 397 398+ Response 200 (application/json) 399 + Body 400 401 ["/opengrok-master/testdata/repositories/teamware", 402 "/opengrok-master/testdata/sources/rfe2575", 403 "/opengrok-master/testdata/repositories/rcs_test", 404 "/opengrok-master"] 405 406## Repository type [/projects/{project}/repositories/type] 407 408### returns types of project repositories [GET] 409 410+ Response 200 (application/json) 411 + Body 412 413 ["RCS","git","SCCS"] 414 415## Project indexed flag [/projects/indexed] 416 417### returns a list of indexed projects [GET] 418 419+ Response 200 (application/json) 420 + Body 421 422 ["sc-2","sc-1"] 423 424## Repository field value [/repositories/property/{field}{?repository}] 425 426### return the field value [GET] 427 428The repository path is relative to source root. Examples of field names: 429 - `working` (boolean) - is the repository capable of running underlying SCM 430 commands 431 - `type` (string) - type of SCM 432 - `remote` (boolean) - is the SCM source remote 433 - `parent` (string) - origin/parent of the SCM 434 - `branch` (string) - branch identification 435 - `currentVersion` (string) - current revision ID 436 - `handleRenamedFiles` (boolean) - whether to handle renamed files for history 437 cache generation 438 - `historyEnabled` (boolean) - is history enabled 439 440The repository path is relative to source root. 441 442+ Response 200 (application/json) 443 444+ Parameters 445 + repository - repository path with native path separators (of the machine 446 running the service) starting with path separator for which to return type 447 448## Search [/search{?full,def,symbol,path,hist,type,projects,maxresults,start}] 449 450## return search results [GET] 451 452+ Parameters 453 + full (optional, string) - full search field value to search for 454 + def (optional, string) - definition field value to search for 455 + symbol (optional, string) - symbol field value to search for 456 + path (optional, string) - file path field value to search for 457 + hist (optional, string) - history field value to search for 458 + type (optional, string) - type of the files to search for 459 + projects (optional, string) - projects to search in 460 + maxresults (optional, string) - maximum number of documents whose hits will be returned (default 1000) 461 + start (optional, string) - start index from which to return results 462 463+ Response 200 (application/json) 464 + Body 465 466 { 467 "time": 13, 468 "resultCount": 35, 469 "startDocument": 0, 470 "endDocument": 0, 471 "results": { 472 "/opengrok/test/org/opensolaris/opengrok/history/hg-export-renamed.txt": [{ 473 "line": "# User Vladimir <b>Kotal</b> <Vladimir.<b>Kotal</b>@oracle.com>", 474 "lineNumber": "19" 475 },{ 476 "line": "# User Vladimir <b>Kotal</b> <Vladimir.<b>Kotal</b>@oracle.com>", 477 "lineNumber":"29" 478 }] 479 } 480 481## Suggester [/suggest{?projects,field,caret,full,defs,refs,path,hist,type}] 482 483### returns suggestions [GET] 484 485+ Parameters 486 + projects (string) - list of projects for which to retrieve suggestions 487 + field - field for which to suggest 488 + caret - position of the caret in the input field 489 + full - value of the Full Search input 490 + defs - value of the Definitions input 491 + refs - value of Symbol input 492 + path - value of the File Path input 493 + hist - value of the History input 494 + type - value of the Type input 495 496+ Response 200 (application/json) 497 + Body 498 499 { 500 "time": 60, 501 "suggestions": [{ 502 "phrase": "package", 503 "projects": ["kotlin"], 504 "score": 387 505 }], 506 "identifier": "pprttq", 507 "queryText": "pprttq", 508 "partialResult":false 509 } 510 511## Suggester configuration [/suggest/config] 512 513### returns suggester configuration [GET] 514 515+ Response 200 (application/json) 516 + Body 517 518 {"enabled":true,"maxResults":10,"minChars":4,"allowedProjects":null, 519 "maxProjects":2147483647, 520 "allowedFields":["defs","path","hist","refs","type","full"], 521 "allowComplexQueries":true,"allowMostPopular":true,"showScores":false, 522 "showProjects":true,"showTime":false,"rebuildCronConfig":"0 0 * * *", 523 "buildTerminationTime":1800,"timeThreshold":2000} 524 525## Suggester popularity data initialization with queries [/suggest/init/queries] 526 527### updates popularity data based on the queries [POST] 528 529+ Request (application/json) 530 + Body 531 532 ["http://localhost:8080/source/search?project=kotlin&full=text"] 533 534+ Response 204 535 536## Suggester popularity data initialization [/suggest/init/raw] 537 538### updates popularity data based on the provided data [POST] 539 540+ Request (application/json) 541 + Body 542 543 [{"project":"kotlin","field":"full","token":"args","increment":100}] 544 545+ Response 204 546 547## Suggester popularity data [/suggest/popularity/{project}{?field,page,pageSize,all}] 548 549### retrieves popularity data for project [GET] 550 551+ Parameters 552 + field - field for which to retrieve data, default: full 553 + page - page of data, default: 0 554 + pageSize - size of the page, default: 100 555 + all - if all data should be retrieved, if true then page and pageSize params are ignored 556 557+ Response 200 (application/json) 558 + Body 559 560 [{"iso":3},{"the":3},{"to":3},{"conform":3},{"-":2}, 561 {"sc_window_set":1},{"_lso_outbound":1},{"missing":1}] 562 563## Suggester data rebuild [/suggest/rebuild] 564 565### rebuilds suggester data for all projects [PUT] 566 567This kicks off suggester data rebuild in the background, i.e. the rebuild will very likely complete some time after the API call returned. 568 569+ Response 204 570 571## Suggester project data rebuild [/suggest/rebuild/{project}] 572 573### rebuilds suggester data for given project [PUT] 574 575This kicks off suggester data rebuild in the background, i.e. the rebuild will very likely complete some time after the API call returned. 576 577+ Parameters 578 + project - project name 579 580+ Response 204 581 582## Status [/status/{uuid}] 583 584### Check the state of API request [GET] 585 586+ Parameters 587 + uuid 588 589+ Response 202 590 591### Delete state associated with API request tracking [DELETE] 592 593This should be done only after the API request is completed, i.e. after the GET request for the API request state 594returns appropriate status code (e.g. 201). 595 596+ Parameters 597 + uuid 598 599+ Response 200 600