1 package com.atlassian.marketplace.client.api;
2
3 import com.atlassian.fugue.Option;
4 import com.atlassian.marketplace.client.MarketplaceClient;
5 import com.atlassian.marketplace.client.MpacException;
6 import com.atlassian.marketplace.client.model.Vendor;
7 import com.atlassian.marketplace.client.model.VendorSummary;
8
9 /**
10 * Starting point for all resources that return vendor information. Use
11 * {@link MarketplaceClient#vendors()} to access this API.
12 * @since 2.0.0
13 */
14 public interface Vendors
15 {
16 /**
17 * Queries a single vendor.
18 * @param id the unique identifier of the vendor
19 * @return the vendor information, or {@link Option#none()} if there is no match
20 * @throws MpacException if the server was unavailable or returned an error
21 */
22 Option<Vendor> getById(VendorId id) throws MpacException;
23
24 /**
25 * Gets a list of vendors.
26 * @param query a {@link VendorQuery} which can constrain the result set
27 * @return the vendors
28 * @throws MpacException if the server was unavailable or returned an error
29 */
30 Page<VendorSummary> find(VendorQuery query) throws MpacException;
31
32 /**
33 * Creates a new vendor. You must be authenticated to perform this action.
34 * <p>
35 * Use {@link com.atlassian.marketplace.client.model.ModelBuilders#vendor} to build a new
36 * {@link Vendor} object.
37 *
38 * @param vendor the vendor to create
39 * @return a {@link Vendor} representing the vendor in its current state after being created
40 * @throws MpacException if the server was unavailable or returned an error
41 */
42 Vendor createVendor(Vendor vendor) throws MpacException;
43
44 /**
45 * Attempts to modify an existing vendor. You must have already queried the current state of
46 * the vendor with {@link #getById(VendorId)}; then, build another instance that includes any
47 * changes you want to make, using
48 * {@link com.atlassian.marketplace.client.model.ModelBuilders#vendor(Vendor)}.
49 *
50 * @param original the existing vendor
51 * @param updated a copy of the vendor that includes some changes
52 * @return the updated vendor (re-queried from the server) if successful
53 * @throws MpacException if the server was unavailable or returned an error
54 */
55 Vendor updateVendor(Vendor original, Vendor updated) throws MpacException;
56 }