@Override public void define(WebService.NewController controller) { WebService.NewAction action = controller.createAction("logs") .setDescription("Get system logs in plain-text format. Requires system administration permission.") .setResponseExample(getClass().getResource("logs-example.log")) .setSince("5.2") .setHandler(this); action .createParam(PROCESS_PROPERTY) .setPossibleValues(stream(ProcessId.values()) .map(ProcessId::getKey) .sorted() .collect(MoreCollectors.toList(ProcessId.values().length))) .setDefaultValue(ProcessId.APP.getKey()) .setSince("6.2") .setDescription("Process to get logs from"); }
@Override public void define(WebService.NewController context) { WebService.NewAction action = context .createAction("list") .setSince("4.2") .setDescription("List web services") .setResponseExample(getClass().getResource("list-example.json")) .setHandler(this); action .createParam("include_internals") .setDescription("Include web services that are implemented for internal use only. Their forward-compatibility is not assured") .setBooleanPossibleValues() .setDefaultValue("false"); }
@Override public void define(WebService.NewController context) { WebService.NewAction indexAction = context.createAction("index") .setInternal(true) .setDescription("Get all localization messages for a given locale") .setResponseExample(getClass().getResource("l10n-index-example.json")) .setSince("4.4") .setHandler(this); indexAction.createParam(LOCALE_PARAM) .setDescription("BCP47 language tag, used to override the browser Accept-Language header") .setExampleValue("fr-CH") .setDefaultValue(ENGLISH.toLanguageTag()); indexAction.createParam(TS_PARAM) .setDescription("Date of the last cache update.") .setExampleValue("2014-06-04T09:31:42+0000"); }
@Override public void define(WebService.NewController controller) { WebService.NewAction action = controller .createAction("show") .setResponseExample(getClass().getResource("show-example.json")) .setHandler(this) .setDescription("Return data used by security reports") .setSince("7.3") .setInternal(true); action.createParam(PARAM_PROJECT) .setDescription("Project, view or application key") .setRequired(true); action.createParam(PARAM_BRANCH) .setDescription("Branch name") .setExampleValue("branch-2.0"); action.createParam(PARAM_STANDARD) .setDescription("Security standard") .setPossibleValues(PARAM_OWASP_TOP_10, PARAM_SANS_TOP_25) .setRequired(true); action.createParam(PARAM_INCLUDE_DISTRIBUTION) .setDescription("To return CWE distribution") .setBooleanPossibleValues() .setDefaultValue("false"); }
@Override public void define(WebService.NewController controller) { WebService.NewAction action = controller.createAction("index") .setDescription("Get source code as line number / text pairs. Require See Source Code permission on file") .setSince("5.0") .setResponseExample(Resources.getResource(getClass(), "example-index.json")) .setInternal(true) .setHandler(this); action .createParam("resource") .setRequired(true) .setDescription("File key") .setExampleValue("my_project:/src/foo/Bar.php"); action .createParam("from") .setDefaultValue(1) .setDescription("First line"); action .createParam("to") .setDescription("Last line (excluded). If not specified, all lines are returned until end of file"); }
@Override public void define(WebService.NewController controller) { NewAction action = controller.createAction(ACTION_COMPONENT_TAGS) .setHandler(this) .setSince("5.1") .setInternal(true) .setDescription("List tags for the issues under a given component (including issues on the descendants of the component)") .setResponseExample(Resources.getResource(getClass(), "component-tags-example.json")); action.createParam(PARAM_COMPONENT_UUID) .setDescription("A component UUID") .setRequired(true) .setExampleValue("7d8749e8-3070-4903-9188-bdd82933bb92"); action.createParam(PARAM_CREATED_AFTER) .setDescription("To retrieve tags on issues created after the given date (inclusive). <br>" + "Either a date (server timezone) or datetime can be provided.") .setExampleValue("2017-10-19 or 2017-10-19T13:00:00+0200"); action.createParam(PAGE_SIZE) .setDescription("The maximum size of the list to return") .setExampleValue("25") .setDefaultValue("10"); }
@Override public void define(WebService.NewController controller) { NewAction show = controller.createAction(ACTION_SHOW) .setDescription("Show a quality profile") .setSince("6.5") .setResponseExample(getClass().getResource("show-example.json")) .setInternal(true) .setHandler(this); show.createParam(PARAM_KEY) .setDescription("Quality profile key") .setExampleValue(UUID_EXAMPLE_01) .setDeprecatedKey("profile", "6.6") .setRequired(true); show.createParam(PARAM_COMPARE_TO_SONAR_WAY) .setDescription("Add the number of missing rules from the related Sonar way profile in the response") .setInternal(true) .setDefaultValue("false") .setBooleanPossibleValues(); }
@Test public void param_null_metadata() { ((WebService) context -> { NewController newController = context.createController("api/rule"); NewAction create = newDefaultAction(newController, "create"); create.createParam("status") .setDefaultValue(null) .setPossibleValues(Collections.emptyList()) .setExampleValue(null); create.createParam("max") .setPossibleValues((Object[]) null); newController.done(); }).define(context); WebService.Action action = context.controller("api/rule").action("create"); assertThat(action.param("status").defaultValue()).isNull(); assertThat(action.param("status").possibleValues()).isNull(); assertThat(action.param("status").exampleValue()).isNull(); assertThat(action.param("max").possibleValues()).isNull(); }
/** * Add predefined parameters related to pagination of results with a maximum page size. * @since 7.1 */ public NewAction addPagingParamsSince(int defaultPageSize, int maxPageSize, String version) { createParam(Param.PAGE) .setDescription(PAGE_PARAM_DESCRIPTION) .setExampleValue("42") .setDefaultValue("1") .setSince(version); createParam(Param.PAGE_SIZE) .setDescription("Page size. Must be greater than 0 and less than " + maxPageSize) .setDefaultValue(String.valueOf(defaultPageSize)) .setMaximumValue(maxPageSize) .setExampleValue("20") .setSince(version); return this; }
/** * Add predefined parameters related to pagination of results. */ public NewAction addPagingParams(int defaultPageSize) { createParam(Param.PAGE) .setDescription(PAGE_PARAM_DESCRIPTION) .setExampleValue("42") .setDeprecatedKey("pageIndex", "5.2") .setDefaultValue("1"); createParam(Param.PAGE_SIZE) .setDescription("Page size. Must be greater than 0.") .setExampleValue("20") .setDeprecatedKey("pageSize", "5.2") .setDefaultValue(String.valueOf(defaultPageSize)); return this; }
/** * Add predefined parameters related to sorting of results. */ public <V> NewParam createSortParams(Collection<V> possibleValues, @Nullable V defaultValue, boolean defaultAscending) { createParam(Param.ASCENDING) .setDescription("Ascending sort") .setBooleanPossibleValues() .setDefaultValue(defaultAscending); return createParam(Param.SORT) .setDescription("Sort field") .setDeprecatedKey("sort", "5.4") .setDefaultValue(defaultValue) .setPossibleValues(possibleValues); }
void define(WebService.NewController controller) { NewAction action = controller.createAction("list") .setDescription("List supported programming languages") .setSince("5.1") .setHandler(this) .setResponseExample(Resources.getResource(getClass(), "example-list.json")); action.createParam(Param.TEXT_QUERY) .setDescription("A pattern to match language keys/names against") .setExampleValue("java"); action.createParam("ps") .setDescription("The size of the list to return, 0 for all languages") .setExampleValue("25") .setDefaultValue("0"); }
@Test public void use_default_value_of_optional_parameter() { Request request = new TestRequest().setPath("api/print"); DumbResponse response = run(request, newWs("api/print", a -> { a.createParam("message").setDefaultValue("hello"); a.setHandler((req, resp) -> resp.stream().output().write(req.param("message").getBytes(UTF_8))); })); assertThat(response.stream().outputAsString()).isEqualTo("hello"); assertThat(response.stream().status()).isEqualTo(200); }
public NewParam createPageSize(int defaultPageSize, int maxPageSize) { return createParam(Param.PAGE_SIZE) .setDeprecatedKey("pageSize", "5.2") .setDefaultValue(String.valueOf(defaultPageSize)) .setMaximumValue(maxPageSize) .setDescription("Page size. Must be greater than 0 and less or equal than " + maxPageSize) .setExampleValue("20"); }
@Test public void use_request_parameter_on_parameter_with_default_value() { Request request = new TestRequest().setPath("api/print").setParam("message", "bar"); DumbResponse response = run(request, newWs("api/print", a -> { a.createParam("message").setDefaultValue("default_value"); a.setHandler((req, resp) -> resp.stream().output().write(req.param("message").getBytes(UTF_8))); })); assertThat(response.stream().outputAsString()).isEqualTo("bar"); assertThat(response.stream().status()).isEqualTo(200); }
public NewParam createPageParam() { return createParam(Param.PAGE) .setDescription(PAGE_PARAM_DESCRIPTION) .setExampleValue("42") .setDeprecatedKey("pageIndex", "5.2") .setDefaultValue("1"); }
@Override public void define(WebService.NewController context) { WebService.NewAction action = context.createAction("set_default_template") .setDescription("Set a permission template as default.<br />" + "Requires the following permission: 'Administer System'.") .setPost(true) .setSince("5.2") .setHandler(this); WsParameters.createTemplateParameters(action); createDefaultTemplateQualifierParameter(action, newQualifierParameterContext(i18n, resourceTypes)) .setDefaultValue(Qualifiers.PROJECT); }
static void defineIsExternalParam(WebService.NewAction action) { action .createParam(PARAM_INCLUDE_EXTERNAL) .setDescription("Include external engine rules in the results") .setDefaultValue(false) .setBooleanPossibleValues() .setSince("7.2"); }
@Test public void fail_if_required_param_has_default_value() { expectedException.expect(IllegalArgumentException.class); expectedException.expectMessage("Default value must not be set on parameter 'api/rule/create?key' as it's marked as required"); ((WebService) context -> { NewController controller = context.createController("api/rule"); NewAction action = newDefaultAction(controller, "create"); action.createParam("key").setRequired(true).setDefaultValue("abc"); controller.done(); }).define(context); }
/** * Add 'selected=(selected|deselected|all)' for select-list oriented WS. */ public NewAction addSelectionModeParam() { createParam(Param.SELECTED) .setDescription("Depending on the value, show only selected items (selected=selected), deselected items (selected=deselected), " + "or all items with their selection status (selected=all).") .setDefaultValue(SelectionMode.SELECTED.value()) .setPossibleValues(SelectionMode.possibleValues()); return this; } }